6 Working with the UIM Sample Web Service

Generating the NI UIM Client JAR File

Building the UIM Sample web service client JAR is required only when you want to modify the web service and have the UIM Integration cartridge use it. To use the web service in client software, you must generate the NI_UimClient.jar file.

To generate the JAR file:

1. Set up the host.properties file. See "Installing the UIM Sample Web Service" for instructions.

2. Execute the All target using the buildUimClient.xml ANT file.

3. Copy the NI_UimClient.jar file from the webarchive\ora_ni_uim_webservices_cartproj folder into the UIM Integration cartridge lib directory.

The NI_UimClient.jar file is generated, which can then be used in client software.

UIM Connection Client Example

Example 6-1 shows the code that you can use to connect the NI UIM Client to UIM.

String userId = dis.getUsername();
String passWd = dis.getPassword();
if (userId == null || passWd == null) {
        logger.warning("Configuration error: Username/Password values are required for UIM Inventory System.");
        throw new ProcessorException(
                        "Configuration error: Username/Password values are required for UIM Inventory System.");
}
 
try {
        logger.finest("invoke new NI_Uim_Impl");
 
        NI_Uim service = new NI_Uim_Impl();
        if (service == null) {
                logger.severe("UIM Web Service initialization error: NI_Uim == null");
                throw new ProcessorException("UIM Web Service initialization error: NI_Uim == null");
        }
 
        logger.finest("invoke service.getNI_UimHTTPPort");
 
        NI_UimPort port = service.getNI_UimHTTPPort(userId.getBytes(), passWd.getBytes());
        if (port == null) {
                logger.severe("UIM Web Service initialization error: NI_UimPort == null");
                throw new ProcessorException("UIM Web Service initialization error: NI_UimPort == null");
        }
 
        logger.finer("UIM WS Endpoint = " + dis.getAddress());
        logger.finest("Setting endpoint on the WS port.");
        Stub stub = (Stub) port;
        stub._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, dis.getAddress());
 
        // Success. Save the connection objects.
        //
        uim_service = service;
        uim_port = port;
}

When uim_port is established, the web service calls are available through uim_port.

Installing the UIM Sample Web Service

Before you install the UIM Sample Web Service, ensure that the following are installed:

• Oracle Communications Design Studio for UIM. See Design Studio Installation Guide.

• Oracle WebLogic Server and UIM, or UIM resources, in an environment accessible to Design Studio. See UIM Installation Guide for information about installing UIM. See UIM Developer's Guide for information about installing UIM resources.

To install the UIM Sample Web Service on UIM:

1. Rename the etc\COMPUTERNAME.properties file to host.properties, where host is the environment name of the computer.

   Note:

   Obtain the environment name for the computer by entering the hostname command at the prompt. The output from this command is the computer environment name.

   This enables the loaded Java project to reflect the environment.

2. Open the host.properties file and set the property fields to reference your WebLogic domain and UIM instance.

3. Save and close the file.

4. (Optional) If you wish to develop the web service in Design Studio, set the following Java Build Path Variables:

   • UIM_LIB: Example C:/wls1036/user_projects/domains/UIM/UIM/lib

   • POMS_LIB: Example C:/OracleCommunications/commsplatform/ws

   • POMS_PLIB: Example C:/OracleCommunications/POMSClient/lib

   • FMW_LIB: Example C:/wls1036/modules

5. In the build.xml file, run the following ANT targets to get the web service ready to build and deploy:

   • clean

   • extract.ear

6. Edit the META-INF\application.xml file and add the following code fragment:

   <module> 
     <web> 
       <web-uri>NI_Uim.war</web-uri> 
       <context-root>NI_Uim</context-root> 
     </web> 
   </module>
   

7. In the build.xml file, run the following ANT targets to build the web service and update the EAR file:

   • generate-from wsdl

   • build-service

   • update.ear

8. Redeploy custom.ear using the WebLogic console.

9. (Optional) If you are installing the Network Integrity UIM Sample Web Service on a UIM instance that is not located on the same server as Design Studio, do not run update.ear. For information about installing UIM on a remote server, see UIM Developer's Guide.

Configuring the Network Integrity UI for the UIM Sample Web Service

To configure the Network Integrity UI for the UIM Sample Web Service:

1. Log in to Network Integrity.

2. Click Manage Import System. The Import System Details page is displayed.

3. In the Name field, enter the name of the import system.

4. In the Address field, enter the following address:

   http://UIM_IPAddress:UIM_Port/NI_Uim/NI_UimHTTP
   

   If UIM is installed with SSL enabled, the UIM URL requires HTTPS.

5. In the User Name field, enter the UIM user name.

6. In the Password field, enter the password of UIM.

About CRUD Operations

The UIM Sample Web Service provides Create, Read, Update, and Delete (CRUD) operations on the following entities:

• Logical Device Entity

• Device Interface Entity

• Media Interface Entity

• Physical Device Entity

• Equipment Entity

• Equipment Holder Entity

• Physical Port Entity

• Channelized Connectivity Entity

The UIM Sample Web Service provides create-association operations between peer entities using:

• linkLogicalPhysicalDeviceRequest: This operation supports horizontal associations. The operation provides associations between the logical device and the physical device.

• linkLogicalPhysicalInterfaceRequest: This operation supports horizontal associations. The operation provides associations between the interface and the physical ports.

The UIM Sample Web Service provides create-parent-and-child associations between entities using link.

The UIM Sample Web Service provides delete associations between parent and child entities and delete associations between peer entities. For these operations, the UIM Sample Web Service uses unLink, which deletes vertical and horizontal associations.

The UIM Sample Web Service provides operations to retrieve an entire device tree using:

• getPhysicalDeviceTree

• getLogicalDeviceTree

About Find Qualifiers

The UIM Sample Web Service defaults to the following attribute values for find-entity operations (see findLogicalDeviceRequest and findPhysicalDeviceRequest) if these qualifiers are not already set:

• id field: EQUALS

• Name: BEGINS_WITH

• Mgmt Ip Address: EQUALS

About the <specType> Entity

The <specType> element is commonly used throughout the UIM Sample Web Service examples (see Example 6-2). The <specType> element is used to identify the entity type. This stages the operations to be executed for a particular Oracle Communications Unified Inventory Management (UIM) API. Set the <name> element to the name of the specification you are using.

<specType>
      <name>?</name>
      <entityType>PHYSICALDEVICE</entityType>
</specType>

Supported Entity Types

The <entityType> element supports the following values:

• LOGICALDEVICE

• DEVICEINTERFACE

• MEDIAINTERFACE

• PHYSICALDEVICE

• EQUIPMENT

• EQUIPMENTHOLDER

• PHYSICALPORT

Response Messages

The following response messages can appear:

• SUCCESS: This message appears with a return value and indicates that an operation has succeeded and is committed to UIM.

• FAILURE: This error message indicates that the operation failed but the UIM rollback was successful.

• Exception messages indicate that an operation failed and the UIM rollback failed. This throws exceptionsInventoryFaultType and ValidationFaultType.

Use the following code pattern to inspect a response and detect an operation FAILURE.

CreateLogicalDeviceRequestType createLogicalDeviceRequestType = new CreateLogicalDeviceRequestType();
 
createLogicalDeviceRequestType.setLogicalDevice(wsLogicalDevice);
 
UIMWebService.checkResponse(uimPort.createLogicalDevice(createLogicalDeviceRequestType));

UIM Sample Web Service Entity Operations

Table 6-2 describes the files included in the UIM Sample Web Service project.

Table 6-3 shows how the UIM Sample Web Service processes various entities.

Enabling Debugging for the Web Service

To enable debugging for the UIM Sample Web Service, which is displayed on the Oracle WebLogic Server console:

1. Open the domain\UIM\config\loggingconfig.xml file.

2. Add the following text to the file:

   <logger name="oracle.communications.inventory.webservice.adapter.ni" additivity="false">
         <level value="debug" />
         <appender-ref ref="stdout"/>
         <appender-ref ref="rollingFile"/>
   </logger>