Skip Headers
Oracle® Enterprise Manager Cloud Control Extensibility Programmer's Reference
12c Release 3 (12.1.0.3)

E25161-12
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

19 Using the Web Services Framework

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:

19.1 About Web Services

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

    https://oms_system:oms_port/em/websvcs/extws
    
  • RESTful web service

    https://oms_system:oms_port/em/websvcs/restful/extws
    

19.1.1 Using SOAP-based Web Services

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:

https://oms_machine:oms_port/em/websvcs/extws/JobControlService?wsdl

All the SOAP-based web service endpoints are based from the following:

https://oms_system:oms_port/em/websvcs/extws/web_service

The following is a list of the exposed SOAP-based web services:

  • JobControlService

    Creates a job and schedules its execution, creates a job in the job library, retrieves the status of job steps, and so on.

  • ProcedureService

    Retrieves deployment procedures, submits a deployment procedure run and so on.

  • SwlibService

    Retrieves software library entities.

19.1.2 Using RESTful Web Services

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:

https://oms_system:oms_port/em/websvcs/restful/extws/cloudservices/service/v0/ssa

The RESTful web service endpoint is based from the following:

https://oms_system:oms_port/em/websvcs/restful/extws/RESTful_URI

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).

19.2 Using APIs to Write Java Clients

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:

oracle.sysman.emSDK.webservices.outbound

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.

19.2.1 About SOAPMessageBuilder

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.

19.2.2 About WebServiceInvoker

When a client program invokes a web service method, there are various areas that need to be addressed, including:

  • Security

  • 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 (com.sun.xml.ws.developer.JAXWSProperties.CONNECT_TIMEOUT)

  • request timeout (com.sun.xml.ws.developer.JAXWSProperties.REQUEST_TIMEOUT)

  • SOAP action (javax.xml.ws.BindingProvider.SOAPACTION_URI_PROPERTY)

These attributes can be set with these corresponding API calls:

  • setConnectTimeout(int connectTimeout)

  • setRequestTimeout(int requestTimeout)

  • setSOAPAction(String soapAction)

WebServiceInvoker exposes four different ways to invoke a web service:

  • invokeSyncWS(SOAPMessage request)

    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 oracle.sysman.emSDK.webservices.outbound.WebServiceAsyncProcessor.

  • invokeAsyncWithHandlerWS(SOAPMessage request, WebServiceAsyncProcessor asyncProcessor, AsyncHandler asyncHandler)

    Same as invokeAsyncWS(), except the results of the method invocation are processed by the handleRepsonse() method of an implementation of javax.xml.ws.AsyncHandler.

  • invokeOneWayWS(SOAPMessage request)

    Calls the method, immediately returns and doesn't expect a response back.

19.2.3 Using the InvokeAPITester Sample Program

The following is a sample test program that uses the WebServiceInvoker API to make Web service calls:

oracle.sysman.emSDKsamples.websvcs.outbound.InvokeAPITester

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:

  • protocol

  • host

  • port

  • path

  • name

    Name is the name in the wsdl:definitions tag in the WSDL.

  • username

    Used for security.

  • password

    Used for security.

  • calling mode

    Calling mode can be sync, async, asynccb or oneway.

  • security mode

    Security mode is UNT.

  • target namespace

    Target namespace is value of targetNamspace in wsdl:definitions tag in the WSDL for the web service.

  • port name

    Port name is the name attribute of port in the WSDL.

  • payload XML

    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 protocol://host:port/path/name