NexJ applications may require the application server to send or push data to the client in real time as it becomes available. For example, with a telephony integration solution, an incoming phone call triggers an event on the application server that notifies a user of an incoming call and loads details into a workspace about the contact who is calling.

To meet the needs of scalability, compatibility with different J2EE containers, and reliability of data, the push notification functionality is separated into two components: the push server and the push redirector.

The push server receives initial client requests, authenticates them, and redirects them to the push redirector.

The push redirector establishes a regular HTTP connection with the push server and listens for notifications coming in on the connection. After clients are authenticated and redirected by the push server, the push redirector establishes a Comet connection with clients and pushes notifications onto that connection. The push redirector is deployed on NexJ Server.

Comet is a communication technique that allows a server to send data to a web browser without the data being explicitly requested by the client. Data streaming and long polling are Comet modes. The push redirector also uses Comet in combination with Java NIO (non-blocking I/O) to disassociate threads from open sockets, creating a scalable push solution.

Push notification types

Three push notification types are available to use in NexJ applications. Long polling and data streaming are Comet modes that require the server to notify the client of new information. Client polling relies on the client to check for updates.

Data Streaming
When the client requests information from the server, the server holds the request indefinitely. As information becomes available to the server, it is pushed to the client by writing it to the output stream of the response continuously.

Data streaming is recommended and used by default if a mode is not specified by the client. Data streaming cannot be used if there is a proxy server between the client and push redirector that does not handle uncommitted server responses for each request and response. If data streaming is not appropriate, the client must request the long polling mode when the client establishes the initial Comet connection.

Long Polling
When the client requests information from the server, the server holds the request until a notification is ready to be pushed to the client. After information becomes available to the server, a completed response is pushed to the client and the connection closes. The client immediately registers for push notifications again in order to continue receiving updates.

Client Polling
The client periodically polls for new data from the server. Because the client is constantly checking for new updates, this solution does not rely on the server for push notifications. However, this mode is neither real time nor scalable and constant client requests can overload the server.

Push redirector and push server configuration properties

You configure push redirector properties and the push type for the push server in the server or environment file.

You set the properties in the server or environment file editor, in the Push Notification subtab of the Overview tab in NexJ Studio.

The following two properties are required:

• Push Redirector URL property
• Push Server URLs property

In addition, you need to do one of the following:

• Specify the Push User and Push Password properties.
• Specify the Push Certificate and Push Password properties.
• Configure SPNEGO authentication for the push redirector.

The properties for configuring the push redirector in the Push Notification subtab are as follows with their environment file attribute names in parentheses:

Push Redirector URL (pushRedirectorURL)
Specifies the host, port, and context path of the push redirector using the following format:
http[s]://<host>[:<port>][/<path>]
For example:
http://localhost:5443/nexj/pushRedirect

You must specify the host. The port and context path are optional. If the port or context path are not specified, the default values are used. The default port is 5443 if SSL is enabled and 5080 if SSL is not enabled. The default context path is /nexj/pushRedirect.
This property is required for using the push redirector.

Push Server URLs (pushServerURLs)
Specifies the list of full paths to each instance of the push server running on each node of the application cluster in the following format:
http[s]://<host>:<port>/<path> [...]
Multiple URLs are separated with a space, for example:
http://app1.local:8080/nexj/push http://app2.local:8080/nexj/push
The context path must be set to match the HTTP URL as defined for the push servers that the push redirector will connect to.
This property is required for using push redirection.

Push Timeout (pushTimeout)
Specifies the amount of time an idle Comet connection between the client and push redirector is considered to be timed out, in milliseconds. If the push redirector fails to respond to a ping after the specified time, the client will revert to periodic polling. If not specified, the default value of 5 minutes is used.

Push User (pushUser)
Specifies the user that authenticates with the NexJ application when connecting to the push server.

If the property is not specified, you must either specify the Push Certificate property or configure the push redirector for SPNEGO authentication.

To be authorized by the push server, the push user must be assigned the PushRedirect privilege in NexJ Admin Console. The NexJ System Administrator user account, the nexjsa user, has this privilege by default.

Push Password (pushPassword)
Specifies the password of the push user when used with the Push User property or the keystore password when used with the Push Certificate property.

The Push Password property must be configured if either the Push User or Push Certificate properties are configured.

Push Certificate (pushCertificate)
Specifies the push certificate that is used for client certificate authentication, which is also known as two-way SSL or mutual authentication, to the push server. The property contains a Base64-encoded keystore that has a private key and certificate.

The user specified in the CN field of the certificate must be able to authenticate with the NexJ application when connecting to the push server.

If you choose not to configure the Push Certificate property, you must configure the Push User property or configure the push redirector for SPNEGO authentication.

See Configuring SPNEGO authentication with the push redirector for more information on setting up SPNEGO authentication with the push redirector.

Push Trust (pushTrust)
Specifies the push server SSL certificate that the push redirector should trust when making an initial connection to the push server with SSL enabled. This property is optional. If the certificate is self signed, it must also be added to the truststore of the push redirector.

See Configuring SSL for the push redirector for more information on setting up SSL between the push redirector and the push server. Also see Configuring SSL between the push redirector and clients for more information on setting up SSL between the push redirector and end users.

Push Disconnect Delay (pushDisconnectDelay)
Specifies, in milliseconds, the interval with which client connections are dropped when the push redirector loses connectivity with the push server. This property is optional. If it is not specified, the default value of 50 milliseconds is used.

In addition to the push redirector properties, a push server property is also available in the Push Notification subtab:

Push Type (pushType)
Specifies the Comet mode that the NexJ Application uses for push notifications. Available push types are data streaming, long polling, and none (client polling). If the NexJ application encounters an issue with the specified mode, fall back occurs from data streaming to long polling to client polling.

See Push notification types for information on push notification types.

Configuring SSL for the push redirector

You can configure SSL between the push redirector and the push server and between the push redirector and clients.

Configuring SSL between the push redirector and push server

You configure SSL between the push redirector and push server by specifying the push server SSL certificate that the push redirector should trust when making an initial connection to the push server.

Secure transport also must be enabled in the server's environment file and the http URL must start with https.

To configure SSL between the push redirector and push server:

1. In NexJ Studio, open the push redirector environment file.
2. In the Overview tab, open the Push Notification subtab.
3. In the Push Trust field, enter the public key that matches the server certificate installed on the push server.
4. Save and close the environment file.

SSL is configured between the push redirector and push server.

Also ensure that you configure SSL between the push redirector and clients.

Configuring SSL between the push redirector and clients

You configure SSL between the push redirector and end users by replacing the default conf\ssl.keystore file with your own private key certificate. This certificate must be trusted by end users connecting to the push redirector. Then, you specify a password for the keystore file in NexJ Studio.

Secure transport also must be enabled in the server's environment file and the http URL must start with https.

To enable SSL for the push redirector:

1. On the push redirector machine, replace the default ssl.keystore:

   1. Obtain a PKCS#12 keystore from a trusted certificate authority (CA).

      Info

      The PKCS#12 keystore should have a CN matching the hostname of the push redirector server.

   2. Copy the PKCS#12 keystore and paste it into the push redirector conf directory. For example, paste the certificate into the %PUSH_REDIRECT%\conf directory.
   3. Delete the default ssl.keystore file.
   4. Rename the PKCS#12 keystore to ssl.keystore.
2. In NexJ Studio, provide the password for the keystore file:
   1. In NexJ Studio, open the push redirector environment file.
   2. In the Type field, ensure the server type is set to Generic.
   3. In the Overview tab, open the Security subtab.
   4. Enter the keystore password value that you obtained when you exported the PKCS#12 file.
   5. Save the environment file. Copy the new environment file into the push redirector conf directory.

SSL is configured between the push redirector and clients.

Also ensure that you configure SSL between the push redirector and the push server.

Configuring SPNEGO authentication with the push redirector

Before SPNEGO authentication can be used with the push redirector, Kerberos service principal names must be set for each application server node. The push user and push password properties are still required in the server or environment file, but correct credentials do not need to be entered.

See Enabling SPNEGO authentication for information on enabling SPNEGO authentication in your server or environment file.

To set up SPNEGO authentication with the push redirector:

1. Configure Kerberos service principal names for each application server node. Kerberos may already be configured for the frontend address, but each node must be added as well.
2. Set the service to run as a service account on the domain. The service account must be a member of the "nexjusers" security group. If you are using a Windows-based service, the environment file’s pushUser property should be left blank. If you are using a Linux-based service, the pushUser and pushPassword properties should be set to the service account’s credentials.
3. Grant the service account Modify permissions on the directory of the push redirector.
4. If the push redirector is currently running, restart it.

You have set up SPNEGO authentication with the push redirector.

Creating the push redirector server

Real-time notification is provided by NexJ Server. The nexj-push-redirector_version.zip file contains everything needed to run a standalone instance of the push redirector, including two batch scripts to run the server.

The file is bundled with the NexJ CRM release package.

The nexj-push-redirector_version.zip file contains the files required to install and run the push redirector. The file is bundled with the NexJ Studio plugin.

To be authorized by the push server, the push user must be assigned the PushRedirect privilege in the NexJ Admin Console. For more information about assigning privileges, see the NexJ CRM Administrator Guide. In addition, the new user must exist in the application server's authentication domain and have membership in the "nexjusers" group. The Java JDK must also be installed and the JAVA_HOME environment variable must be set to the JDK directory.

For development and testing purposes, run the application from NexJ Studio. Configure the push notification settings in the server or environment file, in the Push Notification subtab of the Overview tab.

For production, use the standalone push redirector with the following steps.

Two files within the bin directory can be used to start the push redirector: run.bat and svc.bat. The run.bat file will immediately start the server and the console will output any status messages. The svc.bat file will add the push redirector as a Windows service, allowing you run the server automatically by configuring the service.

To set up a standalone instance of the push redirector:

1. Extract the nexj-push-redirector_version.zip to a location of your choice. Inside the archive file are three directories: bin, conf, and deploy.
2. In the bin directory, edit the desired batch file with a text editor of your choice.
   • If you want to start the push redirector manually, edit run.bat.
   • If you want to add the push redirector as a Windows service, edit svc.bat.
3. Configure the selected batch file using one of three available methods. The first method is recommended for a production environment. See Push redirector and push server configuration properties for information on each property.
   • Place an environment or server file in the conf directory that contains the settings for the push redirector. This method is recommended for use in a production environment to ensure that the environment file is not overwritten when extracting a new version of the push redirector.
   • Define the CONFIG_FILE variable with the location of a configured environment or server file. If files are also present in the conf directory, the file defined in CONFIG_FILE takes precedence.

   • Define the PUSH_PROPS variable with the settings of each property. Each property must be prefixed with -Dnexj. If files are present in the conf directory or CONFIG_FILE is defined, any properties defined in PUSH_PROPS will overwrite the properties within the environment or server files. Here is a sample definition for PUSH_PROPS:

     set PUSH_PROPS=-Dnexj.pushRedirectorURL="http://localhost:5080/nexj/ pushRedirect" -Dnexj.pushServerURLs="http://localhost:8080/nexj/push" - Dnexj.pushUser="nexjsa" -Dnexj.pushPassword="text:nexj"

     Info

     If you are deploying without HTTPS and using the PUSH_PROPS method, add the following property:
     -Dnexj.secureTransport="false"

4. Execute the selected batch file.

   • If you are using run.bat, simply execute the file normally to start the server. No further steps are required.

   • If you are using svc.bat, command line parameters are required to run the program. Follow the steps below to install the service.

   1. Open a command line console and navigate to the bin directory. Enter svc.bat -i to install the push redirector service.

      Info

      The svc.bat script works with both 32-and 64-bit versions of Windows. The script will automatically select the correct version, but you can force the script to use settings for the 32-bit version with the x86 parameter, for example:
      svc.bat -i x86

   2. In the command line, enter services.msc to open the Windows services console. Locate the service named PushRedirector and start the service to run the push redirector. Configure the service as desired.

      Info

      For increased security, set the Windows service to log on using a local service account with limited privileges. Update the permissions on the directory containing the push redirector files to give the service account Modify permissions.

To confirm that the push redirector is connected to the push server, enter the URL of the push server in a web browser, for example: http://localhost:8080/nexj/push. The URL should bring up a webpage that displays the push redirector URL in plain text. If your connection times out and produces error code 500, then the push redirector is not connected.

A log of the server is created with Apache log4j in the log directory. Configure log settings in conf\log4j.properties.

If you installed the push redirector as a Windows service and want to uninstall it, enter svc.bat -u on the command line.

If you started the server with run.bat, stop the server by selecting the server console and pressing Ctrl + C. Enter Y when asked to terminate the process.

Push redirector troubleshooting

If you are not sure that the push redirector is running correctly, use the following suggestions to diagnose or resolve the problems.

• If the NexJ application is running on a clustered application server, then the push redirector needs to be set up to connect to all the nodes in the cluster.

• Check the log file for the push redirector to ensure it has started:
  The log file is named nexj.log and is located in the nexj-push-redirector_version/log directory.
  Look for a string similar to the following:

  ; 15:43:28,420 INFO [..] Connecting push redirector http://<servername>/nexj/ pushRedirect to push server http://<servername>/nexj/push

• Verify that the push redirector is running properly. Using a web browser, access the push server URL at https://<servername>/nexj/push. The returned web page should display the push redirector URL.
  The push server URL is the HTTP Server URL specified in the environment or server file for your deployment, followed by the extension “push”.
  If you receive an HTTP error 500 (internal server error) after a timeout, then the push redirector is not connected.

• Verify that messages are being sent between users:

  1. Using two different browser sessions, log in as two different test users.

  2. Send a message from one user to the other.

  3. In the other session, verify that the message had been received.

• Ensure that the web server and application server names are added to your web browser's trusted sites list:
  The following procedure is for Microsoft Internet Explorer only.

  1. In Internet Explorer, open the Tools menu and select Internet Options.
     The Internet Options dialog opens.

  2. Click the Security tab.

  3. The security options are displayed.

  4. Select the Trusted sites icon, then click Sites.
     The Trusted sites dialog opens.

  5. In the Add this website to the zone field, enter the web server URL for your deployment, then click Add.
     The URL is added to the list of trusted sites in the Websites field.

  6. In the Add this website to the zone field, enter the application server URL for your deployment, then click Add.
     The application server URL is the URL returned after you log into the push redirector login web page.
     The URL is added to the list of trusted sites in the Websites field.

  7. Click Close.
     The Trusted sites dialog closes.

  8. Click OK.
     The changes to the trusted sites list are saved.

Push redirector server sizing

The following table provides recommended sizing for the servers that host the push redirector.

Push servers are lightweight and typically sized similarly to your servers, effectively doubling the number of servers in your web tier.

Client authentication and authorization

Push notification clients are authenticated by the application server running the NexJ Model Engine on which the push server is deployed.

Client connections to the push redirector are authenticated through a three-way handshake brokered by the push server. For more information on this process, see Push notification workflow details.

When the push server authenticates a client, the push server generates a unique client ID which acts as a security token that is shared with the push redirector. The push server then redirects the client to the push redirector, passing the client ID as a parameter.

Push redirector authentication

The push redirector must authenticate itself when it communicates with the application server. This behavior is similar to that of any client interacting with the server.

The authentication protocol is configured in the environment file in the Security subtab in the Overview tab in NexJ Studio. This configuration is a global setting for all authentication performed with the application server.