Coherence 5 2 3 – Turn Websites Into Apps Similar

Coherence allows you to turn any website into a full-blown macOS application in seconds. Simply name your app, type in a URL, and grab a favicon. And, using the power of Google Chrome, Coherence allows each app to have separate settings and extensions. Most notably, Amazon uses the Amazon Appstore to list your app while Google uses Google Play Store. If your Android app connects into Google services, porting your Android app to the Fire OS platform may require you to tap into Amazon services instead. When you're building your app, follow the standard Android documentation. Where there are.

• Coherence 5 2 3 – Turn Websites Into Apps Similar Apps
• Coherence 5 2 3 – Turn Websites Into Apps Similar Site

Before Proceeding:

Consult 'Supported Web Containers' to see if you must perform any application server-specific installation steps.

When deploying Coherence*Web on WebLogic Server you now have these options:

• Use the WebInstaller approach described in this chapter.

• Use the SPI-based installation for WebLogic Server 11gR1 or later. See Chapter 2, 'Using Coherence*Web with WebLogic Server.'

• Use the SPI-based installation for GlassFish Server. See Chapter 3, 'Using Coherence*Web with GlassFish Server'.

This chapter provides instructions on how to use the Coherence*Web WebInstaller to install Coherence*Web for Java EE applications on a variety of different application servers.

This chapter contains the following sections:

4.1 Installing Coherence*Web Using the WebInstaller

Coherence*Web can be enabled for Java EE applications on several different Web containers. To do this, you must run the ready-to-deploy application through the automated Coherence*Web WebInstaller before deploying it. The automated installer prepares the application for deployment. It performs the installation process in two discrete steps: an inspection step and an installation step. For more information about what the installer does during these steps, see 'How the Coherence*Web WebInstaller Instruments a Java EE Application'.

The installer can be run either from the Java command line or from Ant tasks. The following sections describe the Java command-line method. For Ant task-based installation, see 'Coherence*Web WebInstaller Ant Task'.

4.1.1 Application Server-Specific Installation Instructions

All of the Web containers listed in 'Supported Web Containers' that can be installed with the WebInstaller share the same general installation instructions. These instructions are described in 'General Instructions for Installing Coherence*Web Session Management Module'.

A few of the Web containers, such as Caucho Resin, and WebLogic 10.n, require extra, container-specific steps that you must complete before starting the general installation procedure. The following sections describe application server-specific installation steps:

4.1.1.1 Installing on Oracle WebLogic Server 10.n

Complete the following steps to install the Coherence*Web Session Management Module into Oracle WebLogic Server release 10 to 10.2:

1. Obtain the coherence-web.jar file from the coherence/lib directory.

2. For each WebLogic Server 10.n installation that will be running in the server cluster, update the libraries using the following command:

3. Follow the instructions described in 'General Instructions for Installing Coherence*Web Session Management Module' to complete the installation. Use the value WebLogic/10.x for the server type.

4.1.1.2Installing on Caucho Resin 3.1.n

Complete the following steps to install the Coherence*Web Session Management Module into a Caucho Resin 3.1.n server:

1. Obtain the coherence-web.jar file from the coherence/lib directory.

2. For each Caucho Resin installation that will be running in the server cluster, update the libraries using the following command:

3. Follow the instructions described in 'General Instructions for Installing Coherence*Web Session Management Module' to complete the installation. Use the value Resin/3.1.x for the server type.

4.1.2 General Instructions for Installing Coherence*Web Session Management Module

Complete the following steps to install Coherence*Web for a Java EE application on any of the Web containers listed under 'Supported Web Containers'.

If you are installing Coherence*Web for a Java EE application on an Apache Tomcat Server, see also 'Enabling Sticky Sessions for Apache Tomcat Servers' for additional instructions.

If you are installing Coherence*Web for a Java EE application on IBM WebSphere Server, see also 'Decoding URL Session IDs for IBM WebSphere 7.n Servers' for additional instructions.

To install Coherence*Web for the Java EE application you are deploying:

1. Ensure that the application directory and the EAR file or WAR file are not being used or accessed by another process.

2. Change the current directory to the Coherence library directory (%COHERENCE_HOME%lib on Windows and $COHERENCE_HOME/lib on UNIX).

3. Ensure that the paths are configured so that Java commands will run.

4. Complete the application inspection step by running the following command. Specify the full path to your application and the name of your server found in Table 1-1 (replacing the and with them in the following command line):

   The system will create (or update, if it already exists) the coherence-web.xml configuration descriptor file for your Java EE application in the directory where the application is located. This configuration descriptor file contains the default Coherence*Web settings for your application as recommended by the installer.

5. If necessary, review and modify the Coherence*Web settings based on your requirements.

   You can modify the Coherence*Web settings by editing the coherence-web.xml descriptor file. Appendix A, 'Coherence*Web Context Parameters,' describes the Coherence*Web settings that can be modified. Use the param-name and param-value subelements of the context-param parameter to enable the features you want. Table 4-1 describes some examples of different settings.

   Table 4-1 Example Context Parameter Settings for Coherence*Web

   Parameter	Name	Description
   coherence-servletcontext-clustered	true	Clusters all ServletContext (global) attributes so that servers in a cluster share the same values for those attributes, and also receive the events specified by the Servlet Specification when those attributes change.
   coherence-enable-sessioncontext	true	Allows an application to enumerate all of the sessions that exist within the application, or to obtain any one of those sessions to examine or manipulate.
   coherence-session-id-length	32	Enables you to increase the length of the HttpSession ID, which is generated using a SecureRandom algorithm; the length can be any value, although in practice it should be small enough to fit into a cookie or a URL (depending on how session IDs are maintained.) Increasing the length can decrease the chance of a session being purposely hijacked.
   coherence-session-urlencode-enabled	true	By default, the HttpSession ID is managed in a cookie. If the application supports URL encoding, this option enables it.

   
   

6. Complete the Coherence*Web application installation step by running the following command, replacing with the full path to your application:

   The installer requires a validcoherence-web.xml configuration descriptor file to reside in the same directory as the application. The command creates a session-cache-config.xml file in the WEB-INFclasses directory of the application archive file. This file contains the session and cache configuration information.

7. Deploy the updated application and verify that everything functions as expected, using the lightweight load balancer provided with the Coherence distribution. Remember that the lightweight load balancer is not a production-ready utility, in contrast to the load balancer provided by WebLogic Server.

The application can be deployed and run in any of the deployment topologies supported by Coherence: in-process, out-of-process, or out-of-process with Coherence*Extend. See the following sections for information on deploying and running your applications under these topologies. For more information on the topologies themselves, see 'Deployment Topologies'.

4.1.2.1 Deploying and Running Applications In Process

Coherence*Web can be run in-process with the application server. This is where session data is stored with the application server. See 'In-Process Topology' for more information on this topology.

For the application server:

1. Start the application server in storage-enabled mode. Add the system property tangosol.coherence.session.localstorage=true to the Java options of your application server startup script.

2. Deploy the coherence.jar and coherence-web.jar files as shared libraries.

3. Deploy and run your application.

4.1.2.2 Deploying and Running Applications Out-of-Process

In the out-of-process deployment topology, a stand-alone cache server stores the session data and the application server is configured as a cache client. See 'Out-of-Process Topology' for more information on this topology.

The cache server and the application server must use the same cache and session configuration. This configuration is generated in the session-cache-config.xml file by the Coherence*Web WebInstaller. The WebInstaller generates the file in the WEB-INFclasses directory of the instrumented application.

For the cache server:

1. Add the tangosol.coherence.cacheconfig system property to the cache server startup script to locate the file configuration file. You must also include the system property tangosol.coherence.session.localstorage=true to enable storage for the cache server.

2. Add the coherence.jar and coherence-web.jar files to the classpath in the cache server startup script.

   Following is a sample startup script:

For the application server (cache client):

1. Deploy the coherence.jar and coherence-web.jar files as shared libraries.

2. The session-cache-config.xml file should already be present in the WEB-INFclasses directory of the instrumented application.

   By default, the file should specify that local storage is disabled (if you are not sure, you can either inspect the file to confirm that the local-storage element is set to false or add the system property tangosol.coherence.session.localstorage=false to the startup script).

3. Deploy the application to the server.

4.1.2.3 Migrating to Out-of-Process Topology

If you have been running and testing your application with Coherence*Web in-process, you can easily migrate to the out-of-process topology. Simply set up your cache server and application server as described in 'Deploying and Running Applications Out-of-Process'.

4.1.2.4 Deploying and Running Applications Out-of-Process with Coherence*Extend

The out-of-process with Coherence*Extend topology is similar to the out-of-process topology except that the communication between the application server tier and the cache server tier is over Coherence*Extend (TCP/IP). Coherence*Extend consists of two components: an extend client (or proxy) running outside the cluster and an extend proxy service running in the cluster hosted by one or more cache servers. See 'Out-of-Process with Coherence*Extend Topology' for more information on this topology.

In these deployments, there are three types of participants:

• Cache servers (storage servers), which are used to store the actual session data in memory.

• Web (application) servers, which are the Extend clients in this topology. They are not members of the cluster; instead, they connect to a proxy node in the cluster that will issue requests to the cluster on their behalf.

• Proxy servers, which are storage-disabled members (nodes) of the cluster that accept and manage TCP/IP connections from Extend clients. Requests that arrive from clients will be sent into the cluster, and responses will be sent back through the TCP/IP connections.

For the cache server:

Follow the instructions for configuring the cache server in 'Deploying and Running Applications Out-of-Process'. Also, edit the cache server's copy of the session-cache-config.xml file to add the system properties tangosol.coherence.session.proxy=false and tangosol.coherence.session.localstorage=true.

See 'Configure the Cache for Proxy and Storage JVMs' for more information and an example of a session-cache-config.xml file with these context parameters.

For the Web tier (application) server:

Follow the instructions for configuring the application server in 'Deploying and Running Applications Out-of-Process'. Also, complete these steps:

1. Ensure that Coherence*Web is configured to use the Optimistic Locking mode. Optimistic locking is the default locking mechanism for Coherence*Web (see'Optimistic Locking').

2. Edit the application server's copy of the session-cache-config.xml file to add the proxy JVM host names, IP addresses and ports. To do this, add a section to the file. In most cases, you should include the host name and IP address, and port of all proxy JVMs for load balancing and failover.

See 'Configure the Cache for Web Tier JVMs' for more information and an example of a session-cache-config.xml file with a section.

For the proxy server:

With a few changes, the proxy server can use the same cache and session configuration as the application server and the cache server. Edit the session-cache-config.xml file to add these system properties:

• tangosol.coherence.session.localstorage=false to disable local storage.

• tangosol.coherence.session.proxy=true to indicate that a proxy service is being used.

• tangosol.coherence.session.proxy.localhost to indicate the host name or IP address of the NIC to which the proxy will bind.

• tangosol.coherence.session.proxy.localport to indicate a unique port number to which the proxy will bind.

See 'Configure the Cache for Proxy and Storage JVMs' for more information and an example of a session-cache-config.xml file with these context parameters.

4.1.3 Enabling Sticky Sessions for Apache Tomcat Servers

If you want to employ sticky sessions for the Apache Tomcat Server, you must configure the jvmRoute attribute in the server's server.xml file. You can find more information on this attribute at this URL:

4.1.4 Decoding URL Session IDs for IBM WebSphere 7.n Servers

If set to true, the coherence-session-urldecode-bycontainer context parameter allows the container to decode the URL. This context parameter must be set to false if you are installing Coherence*Web for a Java EE application on release 7.n of the IBM WebSphere application server. Instead of the WebSphere application server, Coherence*Web will handle the decoding of session IDs.

Coherence 5 2 3 – Turn Websites Into Apps Similar Apps

The Coherence*Web WebInstaller, when run for the WebSphere 7.n application server type, will automatically set this parameter to false unless you explicitly set it to true.

4.2 Coherence*Web WebInstaller Ant Task

The Coherence*Web WebInstaller Ant task enables you to run the installer from within your existing Ant build files.

This section contains the following information:

4.2.1 Using the Coherence*Web WebInstaller Ant Task

To use the Coherence*Web WebInstaller Ant task, add the task import statement illustrated in Example 4-1 to your Ant build file. In this example, ${coherence.home} refers to the root directory of your Coherence installation.

Example 4-1 Task Import Statement for Coherence*Web WebInstaller

The following procedure describes the basic process of installing Coherence*Web into a Java EE application from an Ant build:

1. Build your Java EE application as you ordinarily would.

2. Run the Coherence*Web Ant task with the operations attribute set to inspect.

3. Make any necessary changes to the generated Coherence*Web XML descriptor file.

4. Run the Coherence*Web Ant task with the operations attribute set to install.

Performing Iterative Development

If you are performing iterative development on your application, such as modifying JavaServer Pages (JSPs), Servlets, static resources, and so on, use the following installation process:

1. Run the Coherence*Web Ant task with the operations attribute set to uninstall, the failonerror attribute set to false, and the descriptor attribute set to the location of the previously generated Coherence*Web XML descriptor file (from Step 2 of 'Using the Coherence*Web WebInstaller Ant Task').

2. Build your Java EE application as you ordinarily would.

3. Run the Coherence*Web Ant task with the operations attribute set to inspect, and the install and descriptor attributes set to the location of the previously generated Coherence*Web XML descriptor file (from Step 2 of 'Using the Coherence*Web WebInstaller Ant Task').

Coherence 5 2 3 – Turn Websites Into Apps Similar Site

Changing the Coherence*Web Configuration Settings of a Java EE Application

If you must change the Coherence*Web configuration settings of a Java EE application that is using Coherence*Web, follow these steps:

1. Run the Coherence*Web Ant task with the operations attribute set to uninstall and the descriptor attribute set to the location of the Coherence*Web XML descriptor file for the Java EE application.

2. Change the necessary configuration parameters in the Coherence*Web XML descriptor file.

3. Run the Coherence*Web Ant task with the operations attribute set to install and the descriptor attribute set to the location of the modified Coherence*Web XML descriptor file (from Step 2 of 'Using the Coherence*Web WebInstaller Ant Task').

4.2.2 Configuring the WebInstaller Ant Task

Table 4-2 describes the attributes that can be used with the Coherence*Web WebInstaller Ant task.

Table 4-2 Coherence*Web WebInstaller Ant Task Attributes

4.2.3 WebInstaller Ant Task Examples

The following list provides sample commands for the WebInstaller Ant task.

• Inspect the myWebApp.war Web application and generate a Coherence*Web XML descriptor file called my-coherence-web.xml in the current working directory:

• Install Coherence*Web into the myWebApp.war Web application using the Coherence*Web XML descriptor file called my-coherence-web.xml found in the current working directory:

• Uninstall Coherence*Web from the myWebApp.war Web application:

• Install Coherence*Web into the myWebApp.war Web application located in the /dev/myWebApp/build directory using the Coherence*Web XML descriptor file called my-coherence-web.xml found in the /dev/myWebApp/src directory, and place a backup of the original Web application in the /dev/myWebApp/work directory:

• Install Coherence*Web into the myWebApp.war Web application located in the /dev/myWebApp/build directory using the Coherence*Web XML descriptor file called coherence-web.xml found in the /dev/myWebApp/build directory. If the Web application has not already been inspected (that is, /dev/myWebApp/build/coherence-web.xml does not exists); inspect the Web application before installing Coherence*Web:

• Reinstall Coherence*Web into the myWebApp.war Web application located in the /dev/myWebApp/build directory, using the Coherence*Web XML descriptor file called my-coherence-web.xml found in the /dev/myWebApp/src directory:

4.3 Testing HTTP Session Management

Coherence comes with a lightweight software load balancer; it is intended only for testing purposes. The load balancer is very easy to use and is very useful when testing functionality such as session management. Follow these steps to test HTTP session management with the lightweight load balancer:

1. Start multiple application server processes on one or more server machines, each running your application on a unique IP address and port combination.

2. Open a command (or shell) window.

3. Change the current directory to the Coherence library directory (%COHERENCE_HOME%lib on Windows and $COHERENCE_HOME/lib on UNIX).

4. Ensure that paths are configured so that Java commands will run.

5. Timerik 1 3. Start the software load balancer with the following command lines (each of these command lines makes the application available on the default HTTP port 80).

   For example, to test load balancing locally on one machine with two application server instances on ports 7001 and 7002:

   To run the load balancer locally on a machine named server1 that load balances to port 7001 on server1, server2, and server3:

   Assuming that you use the preceding command line, an application that previously was accessed with the URL http://server1:7001/my.jsp would now be accessed with the URL http://server1:80/my.jsp or just http://server1/my.jsp.

   Note:

   Ensure that your application uses only relative redirections or the address of the load balancer.

   Table 4-3 describes the command-line options for the load balancer:

   Table 4-3 Load Balancer Command-Line Options

   Option	Description
   backlog	Sets the TCP/ IP accept backlog option to the specified value, for example: -backlog=64
   random	Specifies the use of a random load-balancing algorithm (default).
   roundrobin	Specifies the use of a round-robin load-balancing algorithm
   threads	Uses the specified number of request or response thread pairs (so the total number of additional daemon threads will be two times the specified value), for example: -threads=64.

   
   

4.4 How the Coherence*Web WebInstaller Instruments a Java EE Application

During the inspection step, the Coherence*Web WebInstaller performs the following tasks:

1. Generates a template coherence-web.xml configuration file that contains basic information about the application and target Web container along with a set of default Coherence*Web configuration context parameters appropriate for the target Web container. See Appendix A, 'Coherence*Web Context Parameters' for descriptions of all possible parameters.

   The WebInstaller sets the servlet container to start in storage-disabled mode (that is, it sets tangosol.coherence.session.localstorage to false).

   If an existing coherence-web.xml configuration file exists (for example, from a previous run of the Coherence*Web WebInstaller), the context parameters in the existing file are merged with those in the generated template.

2. Enumerates the JSP from each Web application in the target Java EE application and adds information about each JSP to the coherence-web.xml configuration file.

3. Enumerates the TLDs from each Web application in the target Java EE application and adds information about each TLD to the coherence-web.xml configuration file.

During the installation step, the Coherence*Web WebInstaller performs the following tasks:

1. Creates a backup of the original Java EE application so that it can be restored during the uninstallation step.

2. Adds the Coherence*Web configuration context parameters generated in Step 1 of the inspection step to the web.xml descriptor file of each Web application contained in the target Java EE application.

3. Unregisters any application-specific ServletContextListener, ServletContextAttributeListener, ServletRequestListener, ServletRequestAttributeListener, HttpSessionListener, and HttpSessionAttributeListener classes (including those registered by TLDs) from each Web application.

4. Registers a Coherence*Web ServletContextListener class in each web.xml descriptor file. At run time, the Coherence*Web ServletContextListener class propagates each ServletContextEvent event to each application-specific ServletContextListener listener.

5. Registers a Coherence*Web ServletContextAttributeListener listener in each web.xml descriptor file. At run time, the Coherence*Web ServletContextAttributeListener propagates each ServletContextAttributeEvent event to each application-specific ServletContextAttributeListener listener.

6. Wraps each application-specific Servlet declared in each web.xml descriptor file with a Coherence*Web SessionServlet. At run time, each Coherence*Web SessionServlet delegates to the wrapped Servlet.

7. Adds the following directive to each JSP enumerated in Step 2 of the inspection step:

During the uninstallation step, the Coherence*Web WebInstaller replaces the instrumented Java EE application with the backup of the original version created in Step (1) of the installation process.

4.5 Installing Coherence*Web into Applications Using Java EE Security

Note:

This section does not apply to the native WebLogic Server SPI implementation of Coherence*Web. It applies only if you are using the WebInstaller to install Coherence*Web into an application that uses Java EE security. For instructions on using the SPI implementation, see Chapter 2, 'Using Coherence*Web with WebLogic Server.'

To install Coherence*Web into an application that uses Java EE security, follow these additional steps during installation:

1. Enable Coherence*Web session cookies.

   See the coherence-session-cookies-enabled configuration element in Table A-1 for additional details.

2. Change the Coherence*Web session cookie name to a name that is different from the one used by the target Web container.

   By default, most containers use JSESSIONID for the session cookie name, so a good choice for the Coherence*Web session cookie name is CSESSIONID. See the coherence-session-cookie-name configuration element in Table A-1 for additional details.

3. Enable session replication for the target Web container.

   If session replication is not enabled, or the container does not support a form of session replication, then you will be forced to re-authenticate to the Web application during failover. See your Web container's documentation for instructions on enabling session replication.

This configuration causes two sessions to be associated with a given authenticated user:

• A Coherence*Web session that contains all session data created by the Web application

• A session created by the Web container during authentication that stores only information necessary to identify the user