Device Manager
The Administration API is a set of Java classes used to manage devices, jobs, software, and queries. The Administration API is implemented as a set of Web services, which communicates using SOAP over HTTP. The API consists of a number of proxies, stubs, and support or meta-classes.
The Administration API was used to develop applications that are shipped with Device Manager. External applications, not supplied by Device Manager, can also use the Administration APIs.
The Administration API is supported in two forms:
WSDL is a standard for describing Web services in XML. WSDL supports interoperability and portability between languages and platforms. A WSDL file contains the following characteristics of a Web service:
When using the Administration API contained in the dmapi.jar file, the following additional functions are available:
These functions do not exist in the Administration API generated from the WSDL files. These functions can be added manually to the generated stubs.
The Device Manager Administration API is based on the Web Services for Java 2 Platform, Enterprise Edition (J2EE) JSR-109 specification and the JSR-101 (JAX-RPC) API specification. Web Services for J2EE and JAX-RPC have become the accepted industry standards for Web services.
On the server side, the Device Manager Web services are implemented as stateless session Enterprise JavaBeans (EJBs), instead of Java beans. The following are some advantages of EJB-based Web services, Web Services for J2EE, and JAX-RPC:
Using method-level authorization, you can implement a finer control of the Administration API methods. For example, you can configure the server so that one user can create, delete and modify devices, but another user can only view devices.
The JAX-RPC specification also differentiates between managed (J2EE) and unmanaged (J2SE) client environments. Managed client applications run in a J2EE client container and have access to WebSphere services via JNDI. Managed clients are packaged with a client deployment descriptor:
Servlets, JSPs, EJBs, and WebSphere client applications are examples of managed clients.
Unmanaged clients are stand-alone applications that do not contain client deployment information and do not have access to WebSphere services via JNDI.
The dmapi.jar file supports both the managed and unmanaged client environments.
With Device Manager, version 1.5, the Administration API was based on the WebSphere Apache SOAP run-time which utilized RPC/SOAP encoding. This API still exists and consists of proxies contained in the proxy.soap package. However, the use of these classes is not recommended and is deprecated.
The Web Services for J2EE run-time is the strategic run-time and offers better performance and interoperability. If you wish to continue using applications that use the Apache SOAP run-time, make sure you use the version of the dmapi.jar that comes with Device Manager, version 1.8.
It is recommended that you migrate all Web services that were developed to use the Apache SOAP run-time over to the Web services for the J2EE platform. Proxies for these classes are contained in the com.tivoli.dms.api.proxy package.
The following table lists the Administration API categories. Each API is accessed through a proxy class, and a stub class.
| Web Service | Description | Proxy class (dmapi.jar) | WSDL File |
|---|---|---|---|
| DeviceJobManagerService | Manages jobs submitted to a device | com.tivoli.dms.api.proxy.DeviceJobManagerProxy | DeviceJobManagerService.wsdl |
| DeviceManagerService | Manages devices | com.tivoli.dms.api.proxy.DeviceManagerProxy | DeviceManagerService.wsdl |
| JobManagerService | Manages jobs | com.tivoli.dms.api.proxy.JobManagerProxy | JobManagerService.wsdl |
| NamedQueryManagerService | Manages named queries | com.tivoli.dms.api.proxy.NamedQueryManagerProxy | NamedQueryManagerService.wsdl |
| SoftwareManagerService | Manages software | com.tivoli.dms.api.proxy.SoftwareManagerProxy | SoftwareManagerService.wsdl |
WSDL files can be accessed on the Device Manager server at the following URLs:
The proxy class used the stub class to communicate with the service.
Refer to the Javadoc information for detailed information on the classes and methods for each Administration API.
An application can instantiate any of the Administration API proxies or stubs and invoke methods on them. The stub communicates with a WebSphere Web services servlet on the Device Manager server. The servlet interfaces with the Web service implementation or server code. If you are instantiating the DeviceManagerService Web service, the URL of the DeviceManagerService servlet must be configured in your application as follows:
If you are using WSDL, it defaults to the following location:
http://host_name:80/dmserver/services/DeviceManagerService
If you are using the dmapi.jar file, it defaults to the following location:
http://localhost:80/dmserver/services/DeviceManagerService
The location can be changed in the proxy using the setEndpoint method or in the WSDL files which are used to generate the Administration API.
If you are using HTTPS, the URL must be changed to HTTPS protocol and the port number to 443 (or whatever the SSL port is configured on your server).
The DeviceManagerService servlet receives the Web service request from the client application and forwards it to the service implementation code. Along the way, parameters are encoded and decoded in XML.
If WebSphere Application Server application security is disabled, then the DeviceManagerService servlet will service any valid incoming Device Manager Web service request.
If WebSphere Application Server application security is enabled, then unauthorized users are denied access to the Device Manager server and the Device Manager Administration APIs (an exception is thrown). Therefore, it is recommended that you enable WebSphere Application Server security to prevent unauthorized users from making Administration API calls.
If you are using Basic Authentication for Web Services, that encoding must match the encoding defined using the com.ibm.websphere.security.BasicAuthEncoding WebSphere environment variable. Typically, the value is set to UTF-8.
When writing your Java code, use the sample code for each of the Administration APIs as a guide. The sample code is installed in the DeviceManager/api/samples directory. There are also constants for the Administration API, job types, device classes, configuration parameters, and more contained in com.tivoli.dms.api.ClientAPIConstants.java.
The samples are only for the Administration APIs contained in the dmapi.jar file because the samples use the proxy classes. The samples do not work for the Administration APIs generated from WSDL.
| Related information |
|---|
Additional Device Manager resources
|