C Sample Code

Background

The API architecture and the MetaSolv Solution Application Server architecture both support IOR binding. This type of binding is supported by the server processes creating a flat file containing the stringified object reference. A client can read this object reference from the file, convert it to a real object reference using a CORBA function, and connect to the server.

To create IOR files, the INI parameters are changed in the gateway.ini file. These parameters are the StrictOMG (API only) and IORPath settings. In the API architecture, the StrictOMG parameter needs to be set to true. In the Application Server platform, this parameter is ignored and the IOR is always produced. The IOR is written to the location specified in the IORPath statement. These files are named using the server name with an extension of IOR. These files are produced when the server is initialized.

The server writes the IOR file to disk. Client machines that want to use this mechanism must access this file. There are two ways to accomplish this; distribute the IOR file to the client machine or have the client and server access a shared-drive location. Distributing the IOR can be very problematic because the IOR file is recreated every time the server is restarted. The distribution process must account for this condition. The shared-drive method avoids this problem because both the client and the server access the same drive location. Oracle recommends using the shared-drive approach to access the IOR file.

IOR Bind Method Sample Code

This code example illustrates how to use the IOR binding mechanism.The ”Hello API” sample application code provided with the MetaSolv Solution APIs uses the IOR binding mechanism. The following steps are required to set up the IOR bind mechanism:

1. First set gateway.ini parameters in order for MetaSolv Solution to create an IOR file:

   [System] 
   IORPath=<directoryname>
   
   //Locate the bind code. The code should look something like this.
   ORB.init(args, null);
   String hostname = "MetaSolv Solutionapihost"; //machine name of API host
   String servername = "DLRSERVER"; //MetaSolv Solution API CORBA 
   //server name
   try {
   WDIRoot aWDIRoot = WDIRootHelper.bind(":"+servername, hostname);
   }
   catch (SystemException se) {
   System.out.println("Unable to bind to server: " + se);
   )
   MetaSolv.CORBA.WDI.ConnectReq req = new MetaSolv.CORBA.WDI.ConnectReq();
   //The following values are only examples of the user name and password values.
   req.userName = "ASAP";
   req.passWord = "ASAP";
   WDIManager aWDIManager = aWDIRoot.connect(req);
   

2. Change the code found in item two to read the IOR from a file, convert it to an object, and narrow the scope of the object. After the object is narrowed, then processing can continue as usual. This logic is not placed in program order. For the exact code, reference the sample applications.

   orb = ORB.init(args, null);
   // Connect to the DLR API Server and construct a proxy for the 
   // root object.
   String iorfile = System.getProperties().getProperty(DLR_IOR_FILE_PROPERTY);
   // Set a system property on command line using -D (for Sun) or /d: (for MS)
   // Block A ////////////////////////////////
   if (iorfile == null) 
   throw new Exception("'" + DLR_IOR_FILE_PROPERTY + "' system
   property not set on command line.");
   System.out.println("IOR file="+iorfile);
   String ior = readIOR(iorfile);
   System.out.println("DLR IOR="+ior);
   ////////////////////////////////////////////
   

The block of code above marked Block A shows the changes required. Through standard Java file operations, the IOR string produced by the server is inserted. The name of the file is passed in from a command line parameter. Remember, the client must have access to the IOR file produced by the server. The best way to do this is by accessing a shared drive. The data is read using the readIOR function below.

Here is an extract of the readIOR function. This contains standard Java code to read a file:

private static String readIOR(String fileName) throws IOException
    {
 byte[] iorBytes = new byte[5000]; 
int size = 0;
FileInputStream fs = new FileInputStream(fileName);
      try {
size = fs.read(iorBytes);
 } finally {
fs.close();
      }    
 return new String(iorBytes, 0, size);}

//Block B////////////////////////////////
org.omg.CORBA.Object obj = orb.string_to_object(ior);
WDIRoot aWDIRoot = (WDIRoot)WDIRootHelper.narrow(obj);
/////////////////////////////////////////

The block of code marked Block B above converts the string read from the file into an object reference. This is done using the string_to_object reference. The narrow function takes that object reference and casts it to the correct object type. Once this is done, the remaining code is the same. The code captured below shows how the object reference is used to access other methods. This is the same code used in the bind method without any additional changes.

MetaSolv.CORBA.WDI.ConnectReq req = new
MetaSolv.CORBA.WDI.ConnectReq();
//The following values are only examples of the user name and password values.
req.userName = "ASAP";
req.passWord = "ASAP";
WDIManager aWDIManager = aWDIRoot.connect(req);

Background

A CORBA NameService is a mechanism defined in the CORBA standard for connecting clients and servers. The NameService provides an ”index” of available servers to which it can connect. Each of these servers are found through the use of a name.

The MetaSolv Solution Application Server enables a NameService to facilitate this binding method. There are three methods used to locate the NameService: the IOR file method, the ResolveInitialContext method, and the URL method.

The IOR method of finding the NameService is similar to the process described in the previous section, a file is read that contains the IOR. The IOR is then converted to an object reference for use by the NameService. Sample code is shown later in this section for this bind mechanism.

The resolve_initial_references method of finding the NameService is also available. The resolve_initial_references method is an OMG standard for identifying the NameService. The configuration parameters used by various CORBA vendor's software to find the NameServer varies. Review the documentation provided by your CORBA vendor for details on how the NameService is found. Sample code is shown later in this section for this bind mechanism.

The third method a third party can use to bind to an API running in the MetaSolv Solution Application Server is the URL Bind Method. With this method, an HTTP can be used to get the stringified IOR from the NameService. This type of binding is only supported in the new Application Server architecture.

1. Your first step is to locate the bind code. The code should look something like this:

   ORB.init(args, null);
   String hostname = "MetaSolv Solutionapihost"; // machine name of MetaSolv //Solution API host
   String servername = "DLRSERVER"; // MetaSolv Solution API 
   //CORBA server name
   try {
   //Block C//////////////////////////////////////
   WDIRoot aWDIRoot = WDIRootHelper.bind(":"+servername, hostname);
   ////////////////////////////////////////////////
   }
   catch (SystemException se) {
   System.out.println("Unable to bind to server: " + se);
   )
   MetaSolv.CORBA.WDI.ConnectReq req = new MetaSolv.CORBA.WDI.ConnectReq();
   //The following values are only examples of the user name and password values.
   req.userName = "ASAP";
   req.passWord = "ASAP";
   WDIManager aWDIManager = aWDIRoot.connect(req);
   

2. The next step is to replace it with one of the following two methods:

Binding to the NameServer With an IOR Sample Code

//Block D ////////////////////////////////////
org.omg.CosNaming.NameComponent[] name;
/////////////////////////////////////////////
// Connect to the NameService using the IOR. Published by the
// MetaSolv Solution Application Server
// get the command line parameter
String iorfile = System.getProperties().getProperty(NS_IOR_FILE_PROPERTY); 
// Set a system property on command line using -D (for Sun) or /d: (for MS)
if (iorfile == null)
throw new Exception
("'" + NS_IOR_FILE_PROPERTY + "' system property not set on command line.");

The previous block of code defines the name component variable. The first line of the sample code is an OMG standard variable used for the lookup in the NameService. This variable is used later. The rest of this code obtains the location of the NameService IOR file. The location is passed in as a parameter on the command line of the program. The NameService IOR is written to the location specified in the IORPath statement of the gateway.ini file. This NameService IOR file is named NAMESERVICE.IOR. The best way to locate the file is to have the client and server access a shared-directory location.

System.out.println("IOR file="+iorfile);
String ior = readIOR(iorfile); //read the IOR
System.out.println("NS IOR="+ior);
org.omg.CORBA.Object obj = orb.string_to_object(ior); //convert to object ref
org.omg.CosNaming.NamingContext rootContext =
org.omg.CosNaming.NamingContextHelper.narrow(obj); //narrow the object
System.out.println("loaded orb class:"+orb.getClass().getName());

The previous block of code reads the IOR contained in the file. It converts the IOR to an object reference and narrows the object reference to a CosNaming object. After these steps are completed, the program has the reference to the NameService that is running on the Application Server. The program can now use the NameService to look up the CORBA server it is using.

//populate the name component for lookup
(block A)

name = new org.omg.CosNaming.NameComponent[1];
name[0] = new org.omg.CosNaming.NameComponent("DLRSERVER", "");

// "lookup DLR Server";

(block B)

org.omg.CORBA.Object dlrobj = rootContext.resolve(name);
// narrow the object ref for dlr server
WDIRoot aWDIRoot = (WDIRoot)WDIRootHelper.narrow(dlrobj);

The next step in the process is to look for the actual CORBA server you want to bind to and obtain its object reference from the NameServer. This process is shown in the previous block of code (code block A).

Create the objects used to query the NameService. The Application Server uses a single level of naming. The gateway.ini file controls these names. The ”servers” section connects the name in the NameService to the object. For example:

DLRSERVER=MetaSolv.CORBA.WDIDLR.WDIRoot,MetaSolv.WDIDLR.WDIRootImpl

The name ”DLRSERVER” is registered in the NameService for the object on the right side of the "equals" sign. In the previous code fragment, ”DLRSERVER” was used as the name.

The resolve method is used to look up the object in the NameService (code block B). The resolve method returns a standard CORBA object. This object then needs to be further refined using the CORBA narrow method. After using this command, the root object reference is obtained and the other methods on the server are used. The code fragment below shows this functionality:

MetaSolv.CORBA.WDI.ConnectReq req = new MetaSolv.CORBA.WDI.ConnectReq();
//The following values are only examples of the user name and password values.
req.userName = "ASAP";
req.passWord = "ASAP";
System.out.println("Connecting to MetaSolv Solution API Server...");
WDIManager aWDIManager = aWDIRoot.connect(req);

Binding to the NameService with resolve_initial_references Sample Code

This method of finding the NameService relies on the CORBA standard of resolve_initial_references. This method is available once the ORB has been initialized and provides the object reference of the NameService. Although this method is a CORBA standard, each CORBA vendor implements a different way to locate the NameService. Most of the time configuration parameters such as .INI files are used. Refer to your CORBA vendor's documentation for more details. The following code sample shows how to use this method to connect to the NameService. This code assumes the configuration parameters are set to identify the location of the NameService:

org.omg.CosNaming.NameComponent[] name;

org.omg.CORBA.Object obj = orb.resolve_initial_references("NameService");
org.omg.CosNaming.NamingContext rootContext =
org.omg.CosNaming.NamingContextHelper.narrow(obj); //narrow the object
System.out.println("loaded orb class:"+orb.getClass().getName());

The previous block of code defines the name component variable. This variable is an OMG standard variable used to do the look up in the NameService. It is used later. Next, the object reference of the NameService is obtained and stored in a CORBA object. This is done using the resolve_initial_references method passing in the service name. The CORBA standard for the NameService service is the string ”NameService.” To be useful, cast it into a CosNaming object. This is accomplished using the narrow method. The program can now use the NameService to look up the CORBA server it is using.

//populate the name component for lookup
name = new org.omg.CosNaming.NameComponent[1];
name[0] = new org.omg.CosNaming.NameComponent("DLRSERVER", "");
// "lookup DLR Server";
org.omg.CORBA.Object dlrobj = rootContext.resolve(name);
// narrow the object ref for dlr server
WDIRoot aWDIRoot = (WDIRoot)WDIRootHelper.narrow(dlrobj);

The next step in the process is to look for the actual CORBA server you want to bind to and obtain its object reference from the nameserver. This process is shown in the previous block of sample code. Now create the objects used to query the NameService. The Application Server uses a single level of naming. The gateway.ini file controls these names. The "servers" section connects the name in the NameService to the object. For example:

DLRSERVER=MetaSolv.CORBA.WDIDLR.WDIRoot,MetaSolv.WDIDLR.WDIRootImpl

The name "DLRSERVER" is registered in the NameService for the object on the right side of the "equals" sign. In the previous code fragment, "DLRSERVER" was used as the name.

To look up the object in the NameService, the resolve_initial_references method is used. The resolve method returns a standard CORBA object. This object is refined further using the CORBA narrow method. After using this command, the root object reference is obtained and the other methods on the server are used. The code fragment below shows this process:

MetaSolv.CORBA.WDI.ConnectReq req = new MetaSolv.CORBA.WDI.ConnectReq();
//The following values are only examples of the user name and password values.
req.userName = "ASAP";
req.passWord = "ASAP";
System.out.println("Connecting to MetaSolv Solution API Server...");
WDIManager aWDIManager = aWDIRoot.connect(req);

Sample Code

1. Set gateway.ini parameters to activate this processing in the MetaSolv Solution Application Server. This activation is done by uncommenting the line in the .INI file:

   [System]
   URLNamingServicePort=15000
   

2. Locate the bind code. This bind code should look something like this.

   ORB.init(args, null);
   String hostname = "MetaSolv Solutionapihost"; // machine name of MetaSolv //Solution API host
   String servername = "DLRSERVER"; // MetaSolv Solution API 
   //CORBA server name
   try {
   WDIRoot aWDIRoot = WDIRootHelper.bind(":"+servername, hostname);
   }
   catch (SystemException se) {
   System.out.println("Unable to bind to server: " + se);
   )
   MetaSolv.CORBA.WDI.ConnectReq req = new MetaSolv.CORBA.WDI.ConnectReq();
   //The following values are only examples of the user name and password values.
   req.userName = "ASAP";
   req.passWord = "ASAP";
   WDIManager aWDIManager = aWDIRoot.connect(req);
   

3. Change the code found in item two to read the IOR from the naming service URL, convert it to an object, and narrow the scope of the object. After the object is narrowed the processing can continue as usual.

   orb = ORB.init(args, null);
   
   // Connect to the DLR API Server and construct a proxy for
   // root object.
   String URLref = System.getProperties().getProperty(URL_IOR_FILE_PROPERTY);
   // Set a system property on command line using -D (for Sun) or /d: (for MS)
   //Block E /////////////////////////////////////////////
   URL url = new URL(URLref);
   URLConnection conn = url.openConnection();
   int len = conn.getContentLength();
   if (len == -1) throw new IOException("URL not found: ["+sUrl+"]");
   InputStream in = (InputStream)conn.getContent(); // get the data from the request
   byte[] bior = new byte[len];
   in.read(bior);// read IOR from input stream 
   String ior = new String(bior);// convert to string
   //////////////////////////////////////////////////////
   

The block of code marked Block E above shows the required changes. The URL to connect to is passed in from a command line parameter.

org.omg.CORBA.Object obj = orb.string_to_object(ior);
WDIRoot aWDIRoot = (WDIRoot)WDIRootHelper.narrow(obj);

The block of code above converts the string retrieved from the URL into an object reference. This is done using the string_to_object reference. The narrow function takes that object reference and casts it to the correct object type. Once this is done the remaining code is the same. The code captured below shows how the object reference is used to access other methods. This is the same code used in the bind method:

MetaSolv.CORBA.WDI.ConnectReq req = new
MetaSolv.CORBA.WDI.ConnectReq();
//The following values are only examples of the user name and password values.
req.userName = "ASAP";
req.passWord = "ASAP";
WDIManager aWDIManager = aWDIRoot.connect(req);

Middle-tier Triggering

MetaSolv Solution provides the ability to trigger standard gateway events from the middle-tier server. This behavior occurs in both the API and Application Server environments, which provides a robust triggering method that has many advantages, including maintenance of fewer connections to the third party, enabling automatic retries, and requiring minimum client configuration.

To enable this functionality, two new statuses were added to the gateway events. These statuses indicate the intermediate state between the user asking for a triggering event and the event actually being sent to the third-party applications. A user sees these states in the gateway event status windows located in the work management queue, the PSR order window, and the Trouble report window. These states are:

• Sending: An event in Pending status has been triggered by the user or auto-signaled. The status of the event has changed, but not picked up by the middle-tier triggering server and communicated to the third-party application. When the middle-tier triggering server receives the event and communicates it to a third-party application, the event status changes to "Waiting". If the event cannot be communicated to the third-party application, the status of the event changes to Error.

• Terminating: An event in Waiting or In-progress status has been ”reactivated” by the user using the GUI. These two statuses indicate the third-party application is processing the event. The fact the user has terminated the event must be communicated to the third-party application. The terminating state is the transition state before the event is returned to Pending status and indicates the third-party application was not notified of the status canceling. Once the middle-tier server can communicate this status, the event is changed to Pending.

No third-party coding changes are required to support this new processing. The middle-tier server sending the events uses the same CORBA methods used in the past. The only impact you see is a reduced number of connections. However, some additional parameters are captured when a gateway is defined. This process is described in the next section.

This change only applies to the standard gateway events. The billing and SOA events are not yet converted to this architecture. These events are still invoked directly from the client to the third-party application. This transition will be made in a later release.

Background

As with the MetaSolv Solution Application Server, the MetaSolv Solution gateway event architecture is moving to an OMG standard for binding the client to the server.The reason for this change is to enable the choice of open technologies for Oracle and Oracle customers. IOR binding, and NameService binding are supported.

To enable this support the method of defining gateways in MetaSolv Solution has changed. Additional parameters are defined. Changes are required in the third-party applications to allow the CORBA standard binding. These changes are standard CORBA coding techniques and detailed later in this section.

Defining a Gateway

The way you define a gateway in MSS enables you to trigger events from the middle-tier server and define multiple bind locations.

Figure C-1 shows the Gateway Events window.

Figure C-1 Gateway Events Window

Description of ''Figure C-1 Gateway Events Window''

The Gateway Events window contains the following fields:

• Number of Retries: When a standard gateway event is in Sending status, the middle-tier event server attempts to trigger the event to the third-party application. If the event cannot trigger, a retry process is started. This field indicates how many times a triggering event is retried before the event is marked in error. The default is five.

• Retry Interval (secs): This field indicates the delay before trying to resend an event. This time interval is designed to enable the third-party application time to recover. The default is 30 seconds.

• User ID: This field is required to connect to the third-party application. This field allows one user ID for all connections to the third-party application. This User ID field was added because the middle-tier event server does not have the user ID and password of the user who initiated the event or the definition of every MetaSolv Solution user in the third-party application. The only impact to third-party applications is if they used this user ID for identification of the person initiating the event, this user ID needs to change to the user ID contained within the WDIEvent occurred structure sent with the event (see below). This user ID contains the identification of the actual user who initiated the event. See the code sample below:

  struct WDIEvent
      {
      long    eventVersion;
      string  eventName;
      long    documentNumber;  /// An oracle generated sequence that uniquely
                               /// identifies a Service Request in the MetaSolv
                               /// Solution database. 
      long    taskNumber;      /// An oracle generated sequence that uniquely
                               /// identifies a task in the MetaSolv Solution
                               /// database.
      long    servItemID;      /// An oracle generated sequence that uniquely
                               /// identifies a service item in the MetaSolv
                               /// Solution database. 
                               /// Note this value is only supplied for an 
                               /// item level gateway event. 
      string  userID;          /// A MetaSolv Solution user ID. 
      };
  

  During the upgrade new data is created and the values are used as defaults. If the defaults need to change, each gateway can be edited using the Gateway Events window. The defaults are:

• Number of Retries: 5

• Retry Interval (secs): 30

• UserID: Default

The second change made to gateway maintenance is to enable the definition of multiple binding locations and type of binding to use for each gateway binding location. The type of binding allows the identification of the connection to that gateway. The options are IOR and NameService. Another change is functionality that allows gateways to have multiple bind locations defined. This enables the MetaSolv Solution event architecture to try different locations if it cannot bind to a server. Figure C-2 illustrates binding options:

Figure C-2 MetaSolv Solution Gateway Binding Window

Description of ''Figure C-2 MetaSolv Solution Gateway Binding Window''

The treeview on the left now has the binding information defined. The multi-color lightning bolt represents a binding option. For each binding option, detail information is captured. This is shown on the right side of the window. The following list details the information:

• Binding Type: Indicates what binding mechanism to use for this binding location. The options are IOR and NameService.

• Binding Location: Indicates the path to locate the IOR for binding. This path is used for IOR and NameService binding. This can be expressed as a standard windows path (C:\ior\files) or a URL (http://srvg/ns.ior).

• Binding Service Name: This field indicates the name of the service to request to obtain the WDIRoot reference if using NameService binding.

When multiple binding locations are defined, the bind process attempts to connect them in the order defined in the tree view on the left. Each bind location can use a different binding approach.

During the upgrade, a binding location is created. This binding location has the same host and server name used for previous release. Only one binding location is created.