This chapter explains how to integrate WebCenter Sites with remote applications over the Internet using web services protocols. In the context of the WebCenter Sites development framework, it teaches you how to create and consume basic web services.
This chapter contains the following sections:
Note:
The following feature is deprecated in WebCenter Sites 11g Release 1 (11.1.1.8.0): SOAP-based web services. This feature is replaced by REST services.
WebCenter Sites includes a complete array of asset-delivery functions implemented as web services. These services can be accessed by any technology that can produce a web-services-enabled client. Supplied web-service capabilities are comparable to existing WebCenter Sites APIs (XML, JSP, Java, and COM).
Each supplied service is represented by a predefined WSDL (web services description language) file that contains descriptions of multiple web-services operations. Individual WSDL files define the interface and methods for web-services operations that correspond to WebCenter Sites functions. Related operations are grouped and collectively described according to function.
The WSDL file is used to generate the code required to interact with WebCenter Sites from a client application. You can generate client code automatically using various third-party applications that read WSDL files, or manually by examining the WSDL description and writing the client code from scratch. The resulting client stub constitutes a suitable interface for interaction with WebCenter Sites. When executed, the code creates a SOAP request based on the WSDL operation.
Most times you will have control over the client interaction with WebCenter Sites. For access by potentially unknown client applications, however, the supplied WSDL files can also be posted to a URL and registered via UDDI (universal description, discovery, integration) for remote access.
This section contains the following topics:
Any web services client that supports SOAP and follows the predefined WSDL specifications can access the following information from the WebCenter Sites database:
Site map of a content management site
Blob data, such as a PDF file
List of all the valid asset types and asset subtypes at a content management site
List of assets that match specified search criteria
Metadata associated with a particular asset
Predefined WSDL files for WebCenter Sites are automatically installed with the WebCenter Sites application in the following location:
http://install_dir/futuretense_cs/Xcelerate/wsdl/*.wsdl
The following general steps describe how a request from a web services client program is processed using a supplied WSDL file:
The supplied WSDL file includes a description of the format for the request (input data expected by WebCenter Sites) and the format for the return data. The WSDL file maps standard data types for applications written in Java, Visual Basic, or other programming languages to XML schema data types.
The client program uses instructions in the WSDL to transform data from an input source (for example, a structured file) to an XML schema that is consistent with what the WebCenter Sites web service interface expects.
The client generates a SOAP envelope that includes the required data and transmits it to the content management site.
WebCenter Sites receives the SOAP message.
An XML parser and transformation utility map the data in the SOAP message to the format required by WebCenter Sites.
WebCenter Sites invokes the appropriate seed classes.
Seeds invoke the specified WebCenter Sites action.
WebCenter Sites returns requested data (name/value pairs) in the output format defined by the WSDL file to the client application.
The SOAP processor for the client application maps the XML schema data types to native data types for the specific programming language used.
Data for the predefined WSDL operations is passed using RPC-style interactions (versus exchanging entire XML documents) to your program. These are mostly strings, but WebCenter Sites also includes classes that handle native objects with complex data types; for example, SearchStates and ILists.
Use the WSDL files to generate an interface for your client application. A variety of tools that generate client code from WSDL files are available. These tools support output for different programming languages. Choose a tool that produces code in the target language for your client application, and run it on the WSDL file that describes the operations you need. The resulting client stub makes all WebCenter Sites operations available to your client program.
The code generated from the WSDL file provides an interface to WebCenter Sites functions. Once available, you can call the functions from your application, as needed.
With WebCenter Sites, you can create web services that map data from any WebCenter Sites functions that you want to expose. Because of its support for XML, Java, and JSP, the existing WebCenter Sites development environment provides a familiar platform for developing web services. A supplied tag set enables you to build a SOAP response and stream SOAP encapsulated data to and from applications. As with the prepackaged web services, the WebCenter Sites delivery capability and page-evaluation pipeline are used to process SOAP requests. For web services, the client is a program, not a browser.
This section contains the following topics:
Section 37.2.1, "Process Flow for Creating Custom Web Services"
Section 37.2.2, "Consider Your Data for Custom Web Services"
The following general steps describe how a request from a web services client program is processed:
The client program wraps whatever inputs are required in SOAP and passes them to WebCenter Sites.
The client uses instructions in the WSDL file to transform data from an input source (for example, a structured file) to an XML schema that is consistent with what the WebCenter Sites web service interface expects.
The client generates a SOAP envelope that includes the required data and transmits it to the content management site.
WebCenter Sites receives the SOAP message.
An XML parser and transformation utility map the data in the SOAP message to the format required by WebCenter Sites.
WebCenter Sites invokes the appropriate seed classes.
Seeds invoke the specified WebCenter Sites action.
WebCenter Sites returns requested data (name/value pairs) in the output format defined by the WSDL file to the client application.
SOAP processor for the client application maps the XML schema data types to native data types for the specific programming language used.
Data is passed using RPC-style interactions (versus exchanging entire XML documents) to your program. Consider your data and verify that you will be dealing with simple XSI data types. WebCenter Sites supports all W3C XSI primitive data types without modification.
Note:
Support for complex web-services data types is possible in WebCenter Sites but requires that you create your own Java classes and deploy them on the application server. If you plan to create your own data types, it is recommended that you consult with WebCenter Sites technical support before doing so.
Each web service requires page entry in the SiteCatalog table. The page entry to the SiteCatalog is a name that points to the element that calls the WebCenter Sites function described by your web service. The SiteCatalog stores all valid entries for pages at your site, including those that invoke web services.
The page is invoked by a request from the client. In turn, the response from WebCenter Sites is encapsulated in SOAP and returned to the client. Remember that for web services the client is a program (instead of a browser), and the response is XML (instead of HTML).
To create a WebCenter Sites page for web services
Start Oracle WebCenter Sites Explorer and log in to WebCenter Sites. For instructions, refer to the online help or the instructions in this guide.
In the left pane, open the SiteCatalog table.
Select the folder for your site.
In the pagename field, create an entry for the last part of the page name for your web service in the SiteCatalog table.
In the root element field, create a root entry for your web service. (Including the SiteCatalog entry in the SiteCatalog root avoids a table lookup and ensures that the element name of the first child element is mapped to the specified pagename.)
In either of the resargs fields, add the following optional arguments, if appropriate:
cs.session=false bypasses application server session management for the life of the SOAP request without using existing session objects or creating new session objects on behalf of the current request. This improves performance by reducing the application server load for native requests and requests from clients that do not require session persistence. Although supported on any page, the cs.session=false resarg is mainly intended for use with SOAP services.
cs.contenttype=text/xml prepares the root element for processing. Specifically, it causes the XML engine to properly respect namespace on tags and prevents default HTML compression from occurring. This is required only if you expect the request to come through a browser. Unless the web services request is always received as a SOAP request, you must include this resarg in each SiteCatalog entry to override the HTML compression. Provided that your input XML is well formed, you can be sure that the content output will be proper XML.
In the csstatus field, enter Live, or the appropriate status at this time.
Choose File, then Save All, or click the Save All toolbar button to save your work.
The WebCenter Sites element contains the code for the function you want to expose. The element handles data and formats the SOAP response. To format the SOAP response, include the SOAP XML tags supplied with WebCenter Sites in your code. WebCenter Sites automatically generates the XML for the SOAP envelope.
WebCenter Sites elements written for web services in XML and JSP must not contain extra whitespace or comments because, unlike HTML, XML and its SOAP implementation have stricter parsing requirements. Because XML and JSP pages are handled the same way as HTML pages and are not filtered by WebCenter Sites, extra whitespace or comments can corrupt the SOAP message. Comments (XML or JSP) should appear only after the soap.message tag.
To write an element for a web service
Start Oracle WebCenter Sites Explorer and log in to WebCenter Sites (if you have not already done so). For instructions, refer to the online help or this guide.
In the left pane, select and highlight the ElementCatalog table.
Create a new folder in the ElementCatalog table: choose File, then New Folder.
Select and highlight the new folder, and right-click anywhere in the right pane and select New from the context menu.
A new row appears in the table.
In the elementname field, enter an appropriate name for your web service as the name of the element.
In the description field, enter a short description of the element.
Click in the url field, and click the button that appears.
The New File dialog box displays.
In the Type/Ext field, select XML or JSP as the file type from the drop-down list.
Click OK. Oracle WebCenter Sites Explorer opens its default editor. WebCenter Sites creates a file containing the skeleton code required of all XML or JSP elements. Enter your element code, including the required WebCenter Sites SOAP tags. For example, you can use the following code for XML:
<?xml version="1.0" ?><!DOCTYPE FTCS SYSTEM "futuretense_cs.dtd">
<FTCS Version="1.2">
<!-- WebServices/helloworld
-
- INPUT
-
- OUTPUT--->
<soap.message ns="mynamespace">
<soap.body tagname="HelloWorldOut">
<echoStringOut xsi:type="xsd:string">
<csvar NAME="Variables.echoString"/>
</echoStringOut>
</soap.body>
</soap.message>
</FTCS>
Choose File, then Save All to save your work.
Note:
Choosing File, then Save instead of File, then Save All saves your file, but does not make it available to the application server.
WSDL (web services description language) files describe the web service so that a basic web services client can be automatically generated based on information it contains. If you are not using the predefined services provided with WebCenter Sites, you can optionally create your own WSDL file to describe your web service.
A WSDL file includes the SOAP address, SOAP action, a description of the format for the request (input data expected by WebCenter Sites), and the format for the return data. The WSDL file maps standard data types for applications written in Java, Visual Basic, or other programming languages to XML schema data types. Use any of the predefined WSDL files for WebCenter Sites functions as a template to get started.
A WSDL file has four sections:
Types: specifies the data format and schema definition for operations. The type correlates with return data.
Message: names inputs and outputs. This describes what the WebCenter Sites page must send back.
Operation: describes inputs and outputs.
Binding: specifies the SOAP action and operations.
Service: describes associated port and binding with a URL.
In these sections, specify the following key XML elements:
target namespace
service name
port name
operation name
input parameters (corresponding to simple data types) for the operation. Simple XSI data types (string, integer, float, and so on) return a single value.
Each WSDL file is a collection of interrelated operations, logically grouped together according to their WebCenter Sites function. Completed web services return XML in the form of a SOAP encapsulated response. You will need to understand web services description language to write web services for WebCenter Sites. WebCenter Sites supports WSDL 1.1.
<?xml version="1.0" encoding="utf-8"?>
<definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:s="http://www.w3.org/2001/XMLSchema"
xmlns:s0="http://FatWire.com/someuri/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
targetNamespace="http://FatWire.com/someuri/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<types>
</types>
<message name="HelloWorldIn">
<part name="echoString" type="s:string"/>
</message>
<message name="HelloWorldOut">
<part name="echoStringOut" type="s:string"/>
</message>
<portType name="HelloWorldPortType">
<operation name="helloworld">
<documentation>FOR LATER</documentation>
<input message="s0:HelloWorldIn"/>
<output message="s0:HelloWorldOut"/>
</operation>
</portType>
<binding name="HelloWorldBinding" type="s0:HelloWorldPortType">
<soap:binding transport="http://schemas.xmlsoap.org/soap/
http" style="rpc"/>
<operation name="helloworld">
<soap:operation soapAction="WebServices/" />
<input>
<soap:body use="encoded"/>
</input>
<output>
<soap:body use="encoded"/>
</output>
</operation>
</binding>
<service name="HelloWorld">
<port name="HelloWorldPort" binding="s0:HelloWorldBinding">
<soap:address location="http://localhost:8080/servlet/ContentServer"/>
</port>
</service>
</definitions>