Set up triggered cache manager on HTTP Server (powered by Apache)

The following provides an overview of the process of configuring the triggered cache manager function with the default configuration.

You must write an application to send trigger messages to the triggered cache manager server. Messages your application sends cause the server to update, delete, or publish items in one or more cache targets (specified in the server configuration), using data retrieved from data sources (also specified in the server configuration). For more information on how to write a program to send trigger messages, see Trigger messages for triggered cache manager on HTTP Server (powered by Apache).

Ensure that LPP 5722-DG1 Option 1 is installed on your iSeries™ system and HTTP *ADMIN server is up and running.

1. Start the IBM Web Administration for i5/OS interface.
2. Click the Advanced tab.
3. Click the TCM subtab.
4. Click Create server.
5. Complete the following in the Create server form.

   Field	Description
   Server Name	Enter a name that you will later use to identify this server. For example, JKLTCMServer
   Autostart	Select Yes. This will cause your server to automatically startup when TCP/IP Services is started on your iSeries system. If you do not want your server to startup automatically, select No.
   TCP Port	Use the default value or enter a new TCP Port. You will use this port to communicate with your new server. When the server is started it will establish a listening port on every IP interface configured for TCP/IP Services on your iSeries system. Enter a different port number if you do not want to use this default. Servers cannot share ports so if another server is already configured to use the default port (7049) then you must enter a different, unused port number for this server.
   Options	Use the default, Create with default configuration, or select a new option. If you would rather copy the configuration of a server you have already configured, select Create based on existing configuration and then select that server name.

6. Click Create. The message, "Server 'JKLTCMServer' has been created with default configuration settings" will display at the bottom of your screen.
7. In the list on the left, click Work with servers.
8. Select the server that you just created (for example, JKLTCMServer).
9. Click Start. The message, "A request to start server 'JKLTCMServer' has been submitted" will display at the bottom of your screen. It may take a few minutes for the server to fully activate for the first time (click Refresh periodically until you see the server listed as Active under the Status column).

You have just created and started a triggered cache manager server that uses the default configuration settings provided by IBM. Servers using the default configuration settings are fully operational. IBM has established the following settings for a default configuration:

• A host description named LOCALHOST is defined for IP address 127.0.0.1. To view host descriptions, click Hosts in the list on the left.

  IP address 127.0.0.1 is the 'loopback' interface. The loopback interface is used by many application servers to communicate with each other without using an actual physical network. In this case, the triggered cache manage server uses the loopback interface to communicate with a data source and potential cache target applications that may be added to the configuration (see the section titled Custom configuration, below, for details on how to add custom configuration setting to the default configuration).

• A data source description named LOCAL_HTTP is defined for a local HTTP server. To view data source descriptions, click on Data sources in the list on the left.

  The local HTTP server is assumed to use the default HTTP port (80) on the loopback interface (described previously). The triggered cache manager server communicates with the local HTTP server over the loopback interface to request Web pages it needs to send (or publish) to cache targets.

• A cache target description named LOCAL_DIRECTORY is defined for the local IFS (the iSeries Integrated File System). To view cache target descriptions, click on Cache targets in the list on the left.

  This description specifies the root (/) directory by default. The triggered cache manager server uses the local system's IFS as a cache target.

• Two trigger handler descriptions are set, one named PUBLISH, and the other named UPDATE_CACHE. To view trigger handler descriptions, click on Trigger handlers in the list on the left.

  Both descriptions are set to establish trigger request handlers that manage the cache defined by LOCAL_DIRECTORY using data obtained from the data source defined by LOCAL_HTTP. The trigger request handler named UPDATE_CACHE simply updates cached items by copying them from data source to cache target(s), whereas the trigger request handler PUBLISH may be used to perform dependency parsing and page assembly prior to sending updated items to cache.

• An object dependency graph description named DEFAULT is defined for document publishing. To view object dependency graph descriptions, click on Object dependency graphs in the list on the left.

  By default, the trigger request handler PUBLISH (described previously) is set to use the object dependency graph DEFAULT to record and query information pertaining to Web document dependency parsing and page assembly.

Your application must send trigger messages to one of the request handlers (either UPDATE_CACHE or PUBLISH). This type of application is referred to as an application trigger. When the server receives a trigger message from an application trigger, it places the request in queue for the specified request handler and returns message code 1102 (indicating that the request was accepted). The server then continues to process the request asynchronously.

Servers running with a default configuration may be used in conjunction with application triggers and a local HTTP server (using port 80) to store dynamically produced Web pages as static files in the local file system. An HTTP server may then be used to serve these static files rather than the dynamically produced files, while application triggers ensure the cache of static files are updated only when necessary.

The following section describes how to create customized configurations for the triggered cache manager function.

1. Follow the steps outlined in the previous section, Default configuration, to create and start a new server.
2. Select the server that you just created (for example, JKLTCMServer).
3. Click Hosts.
4. Click Create New Description to add additional host descriptions to the configuration. If you don't want to add additional host descriptions, skip to step 5.
   Note: Host descriptions must be added before certain data source types or cache target descriptions may be added (steps 6d, 8d, and 8e).
   1. Enter the server (or servers) host name or IP address you want this server to use as a data source or cache target (for example, myserver.ibm.com).
   2. Click Create.
   3. To add more host descriptions, repeat steps 4 through 4b.
5. In the list on the left, click Data sources.
6. Click Create New Description to add additional data source descriptions to the configuration. If you don't want to add additional data source descriptions, skip to step 7.
   Note: Data source descriptions must be added before trigger handler descriptions can be added (re: steps 10c and 10d).
   1. Do the following on the first Create data source description form.

      Field	Description
      Name	Enter a name for this description. For example fields for a file system data source, or webDS for an HTTP Server data source.
      Type	Select File System to define a local IFS directory as a data source. Select HTTP Server to define an HTTP server as a data source. For HTTP server data sources, the server hostname or IP address is provided by selecting a host description on the next screen. Host descriptions are not used when defining file system data sources.

   2. Click Next.
   3. If File System was chosen previously, do the following on the second Create data source description form. Otherwise, skip to the next step.

      Field	Directory
      Directory	Enter a directory name that is the data source. For example, /tcm/files All files requested from this data source will be relative to the specified directory.
      Threads	Use the default value or enter a new value. When started, the server will run in a multithreaded process on the iSeries system. It will use the number of specified threads to interact with the data source.

   4. If HTTP Server was chosen previously, do the following on the second Create data source description form.

      Field	Description
      Host	Select the description that describes the HTTP server data source hostname or IP address. Host descriptions were created in steps 4 through 4b. If there is no host description for the data source you are describing, you must first create it by repeating steps 4 through 4b.
      TCP Port	Use the default value or enter a new value. If the HTTP Server data source is not using the default HTTP port, enter it here.
      Root Directory	Select the default, (/). All URLs requested from this data source will be relative to the specified directory (path).
      Keep Alive	Select No. If you know the data source supports persistent HTTP connections, commonly referred to as 'keepalive' support, you may want to select Yes to avoid having the server disconnect after each read request.
      Timeout	Use the default value or enter a new value. Zero (0) indicates the server should wait indefinitely for responses from the data source after requests are sent. If you would rather the server eventually timeout rather than wait indefinitely, enter the number of seconds it should wait before dropping connections. Just remember that an HTTP server may take some time to respond to a request, especially if it needs to dynamically produce the requested file. Be sure to specify a timeout value that is acceptable, otherwise cache targets may not get updated.
      Threads	Use the default value or enter a new value. When started, the server will run in a multithreaded process on the iSeries system. It will use the number of specified threads to interact with this data source. A data source thread is dedicated to fulfill one read request at a time. When threads are waiting for a response from a data source (see Timeout value above), it is not available to send other requests. Be sure to specify enough threads to provide for a number of simultaneous requests acceptable to the data source without overwhelming it.

   5. Click Create.
   6. To add more data source descriptions, repeat steps 6 through 6e.
7. Click Cache targets.
8. Click Create New Description to add additional cache target descriptions to the configuration. If you don't want to add additional cache target descriptions, skip to step 9.
   1. Do the following on the first Create cache target description form.

      Field	Description
      Name	Enter a name for this description. For example fileCT for a file system cache target, or webCT for an HTTP Server cache target, or routerCT for a router cache target. This name is only used to refer to the description you are about to create. It is not used for communication with the cache target.
      Type	Select File System to define a local IFS directory as a cache target. Select HTTP Server to define an HTTP server as a cache target. Select Router to define an IBM model 2212 or IBM model 2216 caching router as a cache target. For HTTP server and router cache targets, the server/router hostname or IP address is provided by selecting a host description on the next screen. Host descriptions are not used when defining file system cache targets.

   2. Click Next.
   3. If File System was chosen previously, do the following on the second Create cache target description form. Otherwise, skip to the next step.

      Field	Description
      Status at Startup	Select Enabled. The server creates an internal handler for each cache target description at startup. These handlers direct the server's interaction with cache targets. This option indicates the initial handler state when the server is started. Requests sent to a disabled cache target handler always appear to be handled successfully (when the handler actually does nothing). This allows you to take cache targets off-line without having failed cache update attempts logged by your triggered cache manager server. When cache targets go on-line again, their corresponding handlers may be re-enabled.
      Directory	Enter a directory name that is the data source. For example: /tcm/filect All files requested from this cache target will be relative to the specified directory.
      Threads	Use the default value or enter a new value. When started, the server will run in a multithreaded process on the iSeries system. It will use the number of specified threads to interact with this cache target.

   4. If HTTP Server was chosen previously, do the following on the second Create cache target description form. Otherwise, skip to the next step.

      Field	Description
      Status at Startup	Select Enabled. The server creates an internal handler for each cache target description at startup. These handlers direct the server's interaction with cache targets. This option indicates the initial handler state when the server is started. Requests sent to a disabled cache target handler always appear to be handled successfully (when the handler actually does nothing). This allows you to take cache targets off-line without having failed cache update attempts logged by your triggered cache manager server. When cache targets go on-line again, their corresponding handlers may be re-enabled.
      Host	Select the description that describes the HTTP cache target source hostname or IP address. Host descriptions were created in steps 4 through 4b. If there is no host description for the cache target you are describing, you must first create it by repeating steps 4 through 4b.
      TCP Port	Use the default value or select a new value. If the HTTP server cache target is not using the default HTTP port, enter it here.
      Root Directory	Use the default, (/). All URLs posted to this cache target will be relative to the specified directory (path).
      Keep Alive	Select No. If you know the cache target supports persistent HTTP connections, commonly referred to as 'keepalive' support, you may want to select Yes to avoid having the server disconnect after each post request.
      Timeout	Use the default value or enter a new value. Zero (0) indicates the server should wait indefinitely for responses from the cache target after requests are sent. If you would rather the server eventually timeout rather than wait indefinitely, enter the number of seconds it should wait before dropping connections. Just remember that an HTTP server may take some time to respond to a request, especially if it needs to dynamically produce the requested file. Be sure to specify a timeout value that is acceptable, otherwise you cannot determine if the cache target received the request.
      Threads	Use the default value or enter a new value. When started, the server will run in a multithreaded process on the iSeries system. It will use the number of specified threads to interact with this cache target. A cache target thread is dedicated to fulfill one post request at a time. When threads are waiting for a response from a cache target (see Timeout value above), it is not available to send other requests. Be sure to specify enough threads to provide for a number of simultaneous requests acceptable to the cache target without overwhelming it.

   5. If Router was chosen previously, do the following on the second Create cache target description form.

      Field	Description
      Status at Startup	Select Enabled. The server creates an internal handler for each cache target description at startup. These handlers direct the server's interaction with cache targets. This option indicates the initial handler state when the server is started. Requests sent to a disabled cache target handler always appear to be handled successfully (when the handler actually does nothing). This allows you to take cache targets off-line without having failed cache update attempts logged by your triggered cache manager server. When cache targets go on-line again, their corresponding handlers may be re-enabled.
      Host	Select the description that describes the hostname or IP address of the router hosting the web document cache target. Host descriptions were created in steps 4 through 4b. If there is no host description for the cache target you are describing, you must first create it by repeating steps 4 through 4b.
      TCP Port	Use the default value or enter a new value. If the router is not using the default port, enter it here.
      Cluster ID	Enter the fully qualified host name or IP address of the web server cluster for which the router is caching documents. This name applies to the name of the web document cache, not the router that is hosting the cache. The router, specified by the Host field, may contain multiple caches for different web server clusters. Use this field to specify which web document cache you want to manage.
      Cluster TCP Port	Enter the TCP port number associated with the cluster ID specified above. The server combines the cluster ID and the cluster TCP port to uniquely identify a cache target hosted by the router.
      Root Directory	Use the default, (/). All URLs posted to this cache target will be relative to the specified directory (path).
      Keep Alive	Select No. If you know the cache target supports persistent HTTP connections, commonly referred to as 'keepalive' support, you may want to select Yes to avoid having the server disconnect after each post request.
      Threads	Use the default, 5. When started, the server will run in a multithreaded process on the iSeries system. It will use the number of specified threads to interact with this cache target. A cache target thread is dedicated to fulfill one post request at a time. When threads are waiting for a response from a cache target it is not available to send other requests. Be sure to specify enough threads to provide for a number of simultaneous requests acceptable to the cache target without overwhelming it.

   6. Click Create.
   7. To add more cache target descriptions, repeat steps 8 through 8f.
9. Click Trigger handlers.
10. Click Create New Description to add additional trigger handler descriptions to the configuration. If you don't want to add additional trigger handler descriptions, skip to step 11.
    1. Do the following on the first Create trigger handler description form.

       Field	Description
       Name	Enter a name for this description. For example simpleDocUpdate for an update cache trigger handler, or docPublisher for a publish trigger handler. The name you choose is used by your application triggers when sending messages to the server. All trigger messages sent to the server must contain the name of the trigger handler that is to process the request.
       Type	Select Update Cache to define a trigger handler that does simple cache updates. Select Publish to define a trigger handler that does document publishing. Update Cache trigger handlers perform simple data transfers. They retrieve objects from a data source and copy them to cache targets. Publish trigger handlers may use object dependency graphs and rule sets to perform dependency parsing and page assembly (prior to doing cache updates). You may use the DEFAULT object dependency graph description included in the default configuration, or you may create and use a new one specifically for your handlers. For more information, click on Publishing rules and Rule set in the list on the left, then click on the help icon in the top-right corner of these pages. If you decide to create your own publishing rules and rule set(s) you may do so, and then return to step 9 to add publish trigger handler descriptions to reference your new rule set(s).

    2. Click Next.
    3. If Update Cache was chosen previously, do the following on the second Create trigger handler description form. Otherwise, skip to the next step.

       Field	Description
       Data Source	Select the description that describes the data source for this trigger handler. Trigger handlers go to one, and only one, data source to retrieve information. The same data source, however, may be used by more than one trigger handler. Data source descriptions were created in steps 6 through 6f. If there is no description for the data source you want your handler to use, you must first create it by repeating steps 6 through 6f.
       Cache Targets	Select the descriptions that describe the cache targets for this trigger handler, or select no descriptions to create a trigger handler that retrieves data but does not sent it to cache. Trigger handlers can manage data for multiple cache targets. Moreover, the same cache target can be managed by more than one trigger handler. Cache target descriptions were created in steps 8 through 8g. If there is no descriptions for the cache targets you want your handler to manage, you may first create them by repeating steps 8 through 8g, or continue on to create this description and then come back to include them later.
       Trigger Queue Collapse Policy	Use the default value. Trigger messages sent from application triggers to a server are always placed on a particular trigger handler's request queue. The handler then processes the requests asynchronously according to the queuing policy specified within the message. It is possible for identical trigger messages to be in queue, either due to the queuing policy or due to the server being overwhelmed by requests. This setting defines how identical triggers in queue are to be handled.
       Cache Request Queue Priority	Use the default value. The same cache target can be managed by more than one trigger handler. Cache update requests from trigger handlers are queued and processed according to priority. This setting defines the priority this handler is to specify when placing cache update requests. The lower the number, the higher the priority. The default is the lowest priority. Enter a lower number if you want this handler to have a higher priority.
       Threads	Use the default value or enter a new value. When started, the server will run in a multithreaded process on the iSeries system. It will use the number of specified threads to process requests sent to this trigger handler.
       Success/ Failures	Use the default value. Trigger handlers can post success or failure messages to acknowledgment targets after requests are handled. This setting allows you to specify the two acknowledgment target lists this handler uses. One list is used to send success messages; the other is used to send failure messages. Default configuration settings do not include acknowledgment target descriptions. If you want your trigger handler to post completion messages, you must first write an application that listens for such messages (using HTTP POST method). You can then add an acknowledgment target description to this server's configuration and reference it here.

    4. If Publish was chosen previously, do the following on the second Create trigger handler description form.

       Field	Description
       Data Source	Select the description that describes the data source for this trigger handler. Trigger handlers go to one, and only one, data source to retrieve information. The same data source, however, may be used by more than one trigger handler. Data source descriptions were created in steps 6 through 6f. If there is no description for the data source you want your handler to use, you must first create it by repeating steps 6 through 6f.
       Cache Targets	Select the descriptions that describe the cache targets for this trigger handler, or select no descriptions to create a trigger handler that retrieves data but does not sent it to cache. Trigger handlers can manage data for multiple cache targets. Moreover, the same cache target can be managed by more than one trigger handler. Cache target descriptions were created in steps 8 through 8g. If there is no descriptions for the cache targets you want your handler to manage, you may first create them by repeating steps 8 through 8g, or continue on to create this description and then come back to include them later.
       Default Include Object	Use the default value. All document component must be triggered before they can be processed by a publish trigger handler. This setting defines an object (by name) that is included during page assembly when neither the source object nor the specified default object in a %fragment tag has been triggered. The default value, none, indicates that such a global default include object is not specified for this handler.
       Object Dependency Graph	Select the DEFAULT description. Publish trigger handlers only use one object dependency graph to record and query object dependency information. The same graph, however, may be used by more than one publish trigger handler.
       Edge Type to Traverse	Use the default value. When publish trigger handlers query an object dependency graph to determine dependency relationships between document components, they traverse a particular edge type (by name). Other edge types, perhaps added by other handlers, are ignored. This setting defines the name of the edge type this handler is to build and traverse. If not specified (the default) a system supplied edge type is used.
       Rule Set	Use the default value. Publish trigger handlers abide by a set of publishing rules when publishing documents. The same rule set, however, may be used by more than one publish trigger handler. If not specified (the default) the default publishing rule is used for all components. For more information, click on Publishing rules and Rule set in the list on the left (after creating this trigger handler description), then click on the help icon in the top-right corner of these pages. If you decide to create your own publishing rules and rule sets you may then change this trigger handler description to reference your new rule sets.
       Threads	Use the default value. When started, the server will run in a multithreaded process on the iSeries system. It will use the number of specified threads to process requests sent to this trigger handler.
       Success/ Failures	Use the default value. Trigger handlers can post success or failure messages to acknowledgment targets after requests are handled. This setting allows you to specify the two acknowledgment target lists this handler uses. One list is used to send success messages; the other is used to send failure messages. Default configuration settings do not include acknowledgment target descriptions. If you want your trigger handler to post completion messages, you must first write an application that listens for such messages (using HTTP POST method). You can then add an acknowledgment target description to this server's configuration and reference it here. The Include object dependency information in acknowledgments option may be used.

    5. Click Create.
    6. To add more trigger handler descriptions, repeat steps 10 through 10e.
11. Click Work with servers.
12. Select the server that you just customized. For example: JKLTCMServer.
13. If your server is listed as "Active" under the Status column, click Stop. Otherwise skip to step 15. The message, "A request to end server 'JKLTCMServer' has been submitted" will display at the bottom of your screen. It may take a few moments for the server end (click Refresh periodically until you see the server listed as "Not Active").
14. Select the server that you just customized. For example: JKLTCMServer.
15. Click Start.
16. The message, "A request to start server 'JKLTCMServer' has been submitted" will display at the bottom of your screen. It may take a few minutes for the server to fully activate for the first time (click Refresh periodically until you see the server listed as "Active" under the Status column).

You have just created, configured, and started a triggered cache manager server using a custom configuration. Your application triggers may now send trigger messages to the active server to request that documents be updated, deleted, or published to the cache targets specified in the configuration.