Learn more about Platform products at http://www.platform.com



Tutorial 2: Register, Locate, and Unregister a Client

This tutorial describes how to register and unregister the client with the EGO Web Service.

Using this tutorial, you will ...


Step 1: Import class references

Import the necessary classes and interfaces that are required by the client to invoke the Web Service.


Step 2: Retrieve cluster and Resource information

The Sample 2 EGOclient class is a subclass of the Sample 1 EGOclient class. Refer to Tutorial 1: Step 2: Retrieve cluster information and Step 3: Retrieve resource information.


Step 3: Register the client

Registration is required in order for clients to be able to request allocations and start activities. The client must also be registered in order to receive notifications for events related to the client's allocations, assigned resources, and activities.

Check if the client can connect to the RegistrationPortType endpoint. If successful, create the RegisterRequestDocument (requestDoc) and RegisterRequest (request) objects. The RegisterRequest object has three member variables: the clientID or name, which must be unique for each client connected to the cluster; a client description; and a URI for the notification endpoint. This endpoint implements the EGO notification WSDL interface. Platform EGO will then send notifications to the client using this endpoint.

Create the security document. The EGO WSDLs and Web Service gateway support Web Service Security (WSSE specification). This means that different types of security information can be passed in the header of SOAP messages sent by the clients. The samples use the simplest form, i.e., username and password authentication. The wrappers generated for Java have signatures that provide for multiple types of security information to be included. In this case, we are using just one security document, which is passed to the register method along with requestDoc and the logonDoc security document.

The response to a registration request has the following sub-elements:

ClientName - the client name that has been assigned to this registration (this will be the same as the optional requested ClientName if the registration is accepted).

AllocationInfo - zero or more elements describing the allocations that have been made previously by this client.

ActivityInfo - zero or more elements describing the activities that have be created previously by this client.

Print out the client name, and the allocation and activity info from the registration response.

public void register(String clientId, String clientDescription, String uri)
	 	 	 throws Exception, RemoteException {
	 	 this.clientId = clientId;
	 	 
	 	 //the default constructor would use the right endpoint
	 	 if (regPort == null) {
	 	 	 try {
	 	 	   regPort = new RegistrationPortTypeStub(null, targetURL);
	 	 	 } catch (Exception e) {
	 	 	 	 e.printStackTrace();
	 	 	   System.err.println("Could not find RegistrationPort...");
	 	 	   return;
	 	 	 }
	 	 }
	 	 // create the RegisterRequest Document
	 	 RegisterRequestDocument requestDoc = RegisterRequestDocument.Factory
	 	 	 	 .newInstance();
	 	 RegisterRequest request = requestDoc.addNewRegisterRequest();
	 	 request.setClientName(clientId);
	 	 request.setClientDescription(clientDescription);
	 	 
	 	 URL ntfURL = new URL(uri);
	 	 ntfPortNumber = ntfURL.getPort();
	 	 
        //TODO Hack until we get Addressing/SoapHeaders to work
	 	 String uriHack = uri; 
	 	 request.setNotificationEndpoint(uriHack);
        request.setOptionArray(new String[]{});
	 	 // create the RegisterResponse Document
	 	 RegisterResponseDocument responseDoc;
	 	 // security documents
	 	 SecurityDocument sdoc1 = SecurityDocument.Factory.newInstance();
	 	 UsernameTokenType usernameTType = getUsernameTokenType(username, password);
        SecurityHeaderType sech1 =
 SecurityHeaderType.Factory.parse(usernameTType.getDomNode());	 	 
        sdoc1.setSecurity(sech1);
	     sdoc1.dump();        	 	 
	 	 logonDoc = sdoc1;
	 	 sdoc1.dump();
	 	 requestDoc.dump();
	 	 responseDoc = regPort.Register(requestDoc, logonDoc);
	 	 RegisterResponse response = responseDoc.getRegisterResponse();
	 	 print(response);
	 	 
	 	 handleRecovery(response);
	 }


Step 4: Locate the client

The Locate operation is used to retrieve information about clients registered with Platform EGO.

Check if the client can connect to the RegistrationPortType endpoint. If successful, create the LocateRequestDocument (lreqDoc) and LocateRequest (lreq) objects. Set the client ID for the LocateRequest object. If no client ID is given, then all registered clients will be returned.

Create the security documents. The wrappers generated for Java have signatures that provide for multiple types of security information to be included. As in the case of client registration, we are using just one security document. Since the Locate method signature has more than one document defined, we pass two empty security documents (sdoc2 and sdoc3) along with lreqDoc and the logonDoc security document.

The response to a locate client request contains zero or more elements of client info.

Print out the client info from the locate client response.

public void locateClients(String clientId) {
	 	 if(this.clientId != clientId) {
	 	 	 System.err.println("This clientId was not registered through this Object...:"
 + clientId);
	 	 }
	 	 if (regPort == null) {
	 	 	 System.err.println("No RegistrationPort exists...");
	 	 	 return;
	 	 }
	 	 try {
	 	 	 LocateRequestDocument lreqDoc = LocateRequestDocument.Factory
	 	 	 	 	 .newInstance();
	 	 	 LocateRequest lreq = lreqDoc.addNewLocateRequest();
	 	 	 //TODO does empty string mean allClients?
	 	 	 lreq.setClientName(clientId);
	 	 	 SecurityDocument sdoc2 = SecurityDocument.Factory.newInstance();
	 	 	 SecurityHeaderType sec2 = sdoc2.addNewSecurity();
	 	 	 SecurityDocument sdoc3 = SecurityDocument.Factory.newInstance();
	 	 	 SecurityHeaderType sec3 = sdoc3.addNewSecurity();

	 	 	 LocateResponseDocument lresDoc = regPort.Locate(lreqDoc, 
	 	 	 	 	 logonDoc, sdoc2, sdoc3);
	 	 	 LocateResponse lres = lresDoc.getLocateResponse();
	 	 	 print(lres);
	 	 } catch (RemoteException rex) {
	 	 	 rex.printStackTrace();
	 	 	 return;
	 	 }
	 }


Step 5: Unregister the client

The Unregister operation is used to terminate an existing EGO registration, which has the effect of terminating all activities started by this client, and releasing all current allocations.

Check if the client can connect to the RegistrationPortType endpoint.

Create the UnregisterRequestDocument (requestDoc) and UnregisterRequest (request) objects. Set the client ID for the UnregisterRequest object.

Create the UnregisterResponseDocument (responseDoc) object. Call the Unregister method and pass the requestDoc and logonDoc objects as input arguments.

public void unregister(String clientId) {
	 	 if(this.clientId != clientId) {
	 	 	 System.err.println("This clientId was not registered through this Object...:"
 + clientId);
	 	 }
	 	 if (regPort == null) {
	 	 	 System.err.println("No RegistrationPort exists...");
	 	 	 return;
	 	 }

	 	 try {
	 	 	 // create the RegisterRequest Document
	 	 	 UnregisterRequestDocument requestDoc = UnregisterRequestDocument.Factory
	 	 	 	 	 .newInstance();
	 	 	 UnregisterRequest request = requestDoc.addNewUnregisterRequest();
	 	 	 request.setClientName(clientId);

	 	 	 // create the RegisterResponse Document
	 	 	 UnregisterResponseDocument responseDoc = UnregisterResponseDocument.Factory
	 	 	 	 	 .newInstance();

	 	 	 responseDoc = regPort.Unregister(requestDoc, logonDoc);
	 	 	 UnregisterResponse response = responseDoc.getUnregisterResponse();
	 	 	 response.dump();

	 	 } catch (RemoteException rex) {
	 	 	 rex.printStackTrace();
	 	 }
	 }


Step 6: Print out the information

The following methods iterate through the various arrays to collect and format the client, activity, and allocation information before printing it out.

public void print(RegisterResponse response) {
	 	 String name = response.getClientName();
	 	 AllocationInfo [] alocinfos   = response.getAllocationInfoArray();
	 	 ActivityInfo   [] actinfos = response.getActivityInfoArray();
	 
	 	 System.out.println("RegisterResponse: " + name);
	 	 print(alocinfos); System.out.println();
	 	 print(actinfos);  System.out.println();
	 }

	 public void print(LocateResponse lres) {
	 	 ClientInfo[] cinfos = lres.getClientInfoArray();
	 	 for (int i = 0; i < cinfos.length; i++) {
	 	 	 ClientInfo cinfo = cinfos[i];
	 	 	 print(cinfo);
	 	 }
	 }

	 public void print(AllocationInfo [] alocinfos)
	 {
	 	 for(int i=0; i<alocinfos.length; i++) {
	 	 	 AllocationInfo ainfo = alocinfos[i];
	 	 	 String id = ainfo.getAllocationID();
	 	 	 String consumer = ainfo.getConsumerName();
	 	 	 AllocationStatus.Enum status = ainfo.getAllocationStatus();
	 	 	 AllocationSpecification aspec = ainfo.getAllocationSpecification();
	 	 	 Resource [] ress = ainfo.getResourceArray();
	 	 	 System.out.printf("%-12s\t%-12s\t%-12s\t", id, consumer, status);
	 	 	 //TODO print aloc spec
	 	 	 for(int j=0; j<ress.length; j++) {
	 	 	 	 System.out.printf("%-12s\t", ress[j].getResourceName());
	 	 	 }
	 	 	 System.out.println();
	 	 }
	 }

	 public void print(ActivityInfo [] actInfos)
	 {
	 	 for (int i=0; i<actInfos.length; i++) {
	 	 	 ActivityInfo ainfo = actInfos[i];
            String id = ainfo.getActivityID();
	 	 	 ActivityState.Enum state = ainfo.getActivityState();
	 	 	 int exitCode = ainfo.getExitStatus().intValue();
	 	 	 String [] exitReason = ainfo.getExitReasonArray();
	 	 	 Calendar start = ainfo.getStartTime();
	 	 	 Calendar end = ainfo.getEndTime();
	 	 	 ActivityResourceUsage rusage = ainfo.getActivityResourceUsage();
	 	 	 ainfo.getResourceNameArray();
	 	 	 System.out.printf("%-12s\t%-12s\t", id, state.toString());
	 	 	 if(state == ActivityState.FINISH) {
	 	 	 	 System.out.printf("%-12d\t", exitCode);
	 	 	 	 for(int j=0; j<exitReason.length; j++) {
	 	 	 	   System.out.printf("%-12s\t", exitReason[j]);
	 	 	 	 }
	 	 	 } else {
	 	 	 	 System.out.printf("%-12d\t%-12d\t%-12d", start, rusage.getUtime(), 
rusage.getStime());
	 	 	 }
	 	 	 System.out.println();
	 	 }
	 }


Run the client application

  1. Select Run > Run.

    The Run dialog appears.

  2. In the Configurations list, either select a Java Application or click New for a new configuration.

    For a new configuration, enter the configuration name.

  3. Enter the project name and Main class.
  4. Click the Arguments tab and enter the following arguments in the given order:
    1. URL of the web service gateway
    2. Port number (string) for the notification interface
    3. Client ID (string)
    4. Client description (string).
      note:   

      Arguments must be separated by a space.

  5. Click Apply and then Run.

Sample Output

[ Top ]


[ Platform Documentation ]


      Date Modified: July 12, 2006
Platform Computing: www.platform.com

Platform Support: support@platform.com
Platform Information Development: doc@platform.com

Copyright © 1994-2006 Platform Computing Corporation. All rights reserved.