|Oracle® Enterprise Manager Cloud Control Extensibility Programmer's Reference
12c Release 3 (220.127.116.11)
|PDF · Mobi · ePub|
In a service based architecture, web services are web-based applications that use XML standards and transport protocols to exchange data with clients. Web Service Definition Language (WSDL) is used to describe the available services and Simple Object Access Protocol (SOAP) is used to transfer the data in a request and response model over HTTP. XML is used to tag the data. Web Application Definition Language (WADL) describes RESTful web services that are invoked through HTTP requests. These standard interfaces allow the web service functionality to be exposed without the need for the client to know more specific information on how the web service is implemented.
This chapter contains the following sections:
In Enterprise Manager Cloud Control 12c, there are a number of SOAP-based and RESTful web services that are exposed for external use.
For SOAP-based web services, WSDL (Web Service Definition Language) defines the contract of the how the web services are exposed.
For RESTful web services, WADL (Web Application Description Language) defines the web service.
Use WSDL and WADL to write the web service client code. The common deployment endpoints for these web services are as follows, where oms_system is the host name and oms_port is the port number of the system where Oracle Management Service is running:
SOAP-based web service
RESTful web service
The WSDL for SOAP-based web services can be obtained by using a browser with the URL of the web service with
?wsdl appended to the URL. For example, the URL for the JobControlService WSDL is as follows:
All the SOAP-based web service endpoints are based from the following:
The following is a list of the exposed SOAP-based web services:
Creates a job and schedules its execution, creates a job in the job library, retrieves the status of job steps, and so on.
Retrieves deployment procedures, submits a deployment procedure run and so on.
Retrieves software library entities.
The WADL for RESTful web services can be obtained by performing a HTTP OPTIONS call on the URI of the web service. For example, the URI for the EMCloudServlet is as follows:
The RESTful web service endpoint is based from the following:
The following is a list of the exposed RESTful web service URIs:
EMCloudServlet - cloudservices/service/v0/ssa
Accesses clouds, zones, service templates, assembly templates, and so on from within a cloud environment.
PaasZoneAPI - cloudservices/admin/cfw/v1/paaszones
Manipulates and views Platform as a Service zones.
SoftwarePoolAPI - cloudservices/admin/cfw/v1/softwarepools
Manipulates and views software pools.
SSARestCatalogAPI - cloudservices/admin/cfw/api
Returns cloud-related web service URIs (that is, paaszones and softwarepools).
The web services framework offers two APIs in the following package to assist in the writing of Java clients that make SOAP-based web service invocations:
The SOAPMessageBuilder API can be used to build a payload SOAPMessage object by inserting items into the SOAP header and the SOAP body of the message. The resultant SOAPMessage can then be used by the WebServiceInvoker API to invoke a web service method.
This API offers different methods to construct a SOAP message. In addition, it allows the caller to set the actor, role, mustUnderstand, and relay attributes of the SOAP header element. Finally, the SOAP body of the message can be constructed with this API.
createSOAPMessage() - create a empty SOAP message.
setHeaderElementActor() - set the recipient of a SOAP header (SOAP1.1).
setHeaderElementRole() - set the recipient of a SOAP header (SOAP 1.2).
setHeaderElementMustUnderstand() - indicates whether a header entry is mandatory or optional for the recipient to understand.
setHeaderElementRelay() - indicates whether the header is to be relayed to the next SOAP node if the current node doesn't understand the header.
addToSOAPHeader() - add name/value pairs of elements and attributes to the SOAP header.
addSOAPHeader() - add a DOM representation of a SOAP header.
addSOAPBody() - add a DOM representation of a SOAP body.
addSOAPPayload() - add entire SOAP message in XML format.
getSOAPMessage() - returns constructed SOAP message.
When a client program invokes a web service method, there are various areas that need to be addressed, including:
Setting up optional client-side SOAP message handlers
Setting the attributes of the request
Different modes of making the call
There are numerous predefined web service security policies that are available through Oracle Web Service Manager with WebLogic Server in the areas of message-level and transport-level security.
As Enterprise Manager web services support the oracle/wss_username_token_service_policy, the WebServiceInvoker API offers setUpUNTAuth(String username, String password) to set up the corresponding client-side security. The API also has setUpHttpBasicAuth(String username,String password) for calls out to other web services that support that security scenario.
If desired, a client program can have client-side SOAP message handlers that modify parts of the SOAP message before it is actually sent to the server. To that end, custom SOAP message handlers that implement the javax.xml.ws.handler.soap.SOAPHandler interface can be written. To associate one with your client progam, the addClientSideSOAPMsgHandler(String handlerClass) API can be called.
There are some basic attributes of a web service method invocation that can be specified by the client. They include:
connection timeout (
request timeout (
SOAP action (
These attributes can be set with these corresponding API calls:
WebServiceInvoker exposes four different ways to invoke a web service:
calls the method and waits for a response.
invokeAsyncWS(SOAPMessage request. WebServiceAsyncProcessor asyncProcessor)
calls the method and loops through the process() method of an implementation of
invokeAsyncWithHandlerWS(SOAPMessage request, WebServiceAsyncProcessor asyncProcessor, AsyncHandler asyncHandler)
invokeAsyncWS(), except the results of the method invocation are processed by the
handleRepsonse() method of an implementation of
Calls the method, immediately returns and doesn't expect a response back.
The following is a sample test program that uses the WebServiceInvoker API to make Web service calls:
It is written to be flexible in that an input file of parameters is read and depending on the values of some of the parameters, the security mode and the invocation mode can be specified. The list of parameters that can be specified include:
Name is the name in the wsdl:definitions tag in the WSDL.
Used for security.
Used for security.
Calling mode can be sync, async, asynccb or oneway.
Security mode is UNT.
Target namespace is value of targetNamspace in wsdl:definitions tag in the WSDL for the web service.
Port name is the name attribute of port in the WSDL.
Payload XML points to an XML file that contains the SOAP message for the request.
default payload XML path
Default payload XML path is the directory in which the payload file is located.
client-side SOAP message handler class
Handler class can specify a client-side SOAP message handler to manipulate the SOAP message before it is sent.
Note:The web service endpoint is constructed as