This tutorial walks you through an example of Java client application code that changes the priority of specified sessions via the Admin Web Service interface. This tutorial was prepared for users that are already familiar with Web Services.
For information about Web Service concepts, refer to the Web Service clients section of the Application Development Guide in the Knowledge Center.
To better understand how the client connects to the Symphony, let’s look at the sequence of events from start-up.
The service controller starts the session director server as a service.
Upon startup, the session director listens for incoming connections from clients. The session director also registers with EGO as a client and uses its connection URL as the client description.
The Symphony client retrieves the connection URL to session director by passing the session director client name in an API call to EGO and retrieving the client description (connection URL).
We will review an example of client code to show how you can create a Java client application that modifies the session priority for a given application. The Java client code in this example is representative of the code you would use to access the proxy stub generated from Axis2.
You can access additional documentation such as the Web Services WSDL Reference, Java API Reference, the Platform Symphony Reference, and the Error Reference from the Platform Symphony or Symphony DE Knowledge Centers.
Create an EGO client object by calling the EGOclient constructor and passing the EGO Web Service Gateway URL as an input argument. Use the initializePorts() method to set up a connection to each web service interface (port) that is required for this tutorial.
The session director (one per cluster) is responsible for authenticating clients and processing their requests. For the client to connect to the session director, it must know its URL. To get the session director's URL, pass the client name "SD_ADMIN" to the locate() method of the egoClient object. This method connects to the EGO web service gateway and retrieves all the client information associated with the session director including its URL, which is stored in the client description property of the ClientInfo object. The session director URL is in the form of domain name and port number. For more information about the locate() method, refer to the Web Services WSDL Reference in the Knowledge Center.
Prepend the communication protocol (http://) to the URL to complete it. Create a new proxy object and initialize it with the session director URL. This sets up a connection to the session director via a web service interface (port).
To view a list of all registered applications, we pass an empty string to the viewApp() method.
For the client to interact with Symphony, it must first be authenticated by the session director. This requires that the client present a security credential. To acquire the credential, set up the security header using the setSecurityHeader() method. The logon method uses a plain text username and password that are sent over an SSL-enabled connection. The method returns the encrypted credential, which is stored in security document securityDoc. For more information about the logon() method, refer to the Web Services WSDL Reference in the Knowledge Center.
The following XML snippet demonstrates how the actual security header with username and password would appear on the wire.
Since the Symphony admin Web Service uses document-style binding, the SdViewAppDocument and SdViewAppResponseDocument classes represent the XML documents that are exchanged between the Web Service and the client. The viewAppReq and resp classes represent the data.
An object of type SdViewAppDocument (viewAppReqDoc) and securityDoc, which has been initialized with the encrypted credential, is passed to the local proxy method, sdViewApp(). The Web Service returns the list of registered applications and the result is printed out to the console using the overloaded print() method.
To view a list of all sessions associated with a specific application, we pass the application name and a string ("0") for session ID to the viewSession() method.
Set up the security document securityDoc by calling the setSecurityHeader() method; see Step 2: List all the applications registered with Symphony.
Create the request document viewSessionReqDoc and its associated request message object viewSessionReq. Initialize the viewSessionReq object with the application name and session ID that, in this case, is set to "0" to denote all sessions.
Call the local proxy method sdViewSession() and pass the request document viewSessionReqDoc and securityDoc as input arguments. The Web Service returns a list of all open sessions including session attributes, which is printed out to the console using the overloaded print() method.
The modSession() method accepts four input arguments: application name, session ID, session tag, priority. All these input arguments, with the exception of session ID, are provided as arguments when you run the main() program. The session ID is initialized to 0 to indicate to the middleware that you want to modify the priority for sessions that share the specified session tag.
Set up the security document securityDoc by calling the setSecurityHeader() method; see Step 2: List all the applications registered with Symphony.
Create the request document modSessionReqDoc and its associated request message object modSessionReq. Initialize the modSessionReq object with the application name, session ID, session tag, and the new priority.
If the system is configured for the session director to fail over on different hosts, the Web Service client has to be written in a way to ensure that the request is sent to the correct session director URL. In the following example, code has been added to the example from step 3 to handle session director failover situations.
First, we initialize the retry variable so that a reconnection to the session director is attempted up to three times. The sdViewSession() method is called and if it succeeds, the variable is reset to zero and the loop exits. If the method call fails, relocateSD() makes an attempt to find the new host that the session director is running on. If the URL is found, it is passed to the soamStub object and the sdViewSession() method call is attempted again; otherwise, a RemoteException is thrown indicating that the session director cannot be found.