Beruflich Dokumente
Kultur Dokumente
Page 1 of 50
Developing Web Services with Documentum INTRODUCTION......................................................................................................................... 4 INDUSTRY MOMENTUM ................................................................................................................ 4 ABOUT THIS DOCUMENT............................................................................................................... 4 THE DOCUMENTUM ECM PLATFORM .............................................................................. 4 WEB SERVICES OVERVIEW................................................................................................... 5 WEB SERVICES DEVELOPMENT .................................................................................................... 6 WEB SERVICES AND DOCUMENTUM CONTENT APPLICATIONS ............................. 7 PRESENT DAY ENTERPRISE SYSTEMS ........................................................................................... 7 BOF Example ........................................................................................................................... 7 EXTENDING THE REACH OF DOCUMENTUM ECM......................................................................... 8 Web Services Roles in ECM ..................................................................................................... 9 EXPOSING CONTENT MANAGEMENT COMPONENTS ...................................................................... 9 Portals ...................................................................................................................................... 9 Developers and Architects ..................................................................................................... 10 Corporations .......................................................................................................................... 10 INVOKING WEB SERVICES .......................................................................................................... 10 WEB SERVICES AND DOCUMENTUM TODAY................................................................ 11 Documentum DFC-based Web Services ................................................................................ 12 Web Services and Documentum in Production Today ........................................................... 14 DFC 4.x vs DFC 5.x ............................................................................................................... 15 OTHER CONSIDERATIONS FOR DEVELOPING WEB SERVICES BASED APPLICATIONS ........................................................................................................................ 16 SESSION MANAGEMENT .............................................................................................................. 16 Overview................................................................................................................................. 16 SECURITY ................................................................................................................................... 19 EXAMPLES AND APPENDICES ............................................................................................ 19 SUMMARY ................................................................................................................................. 20 APPENDIX A: GETTING STARTED DEVELOPMENT TOOLS ................................... 21 APPENDIX B: INTRODUCTION TO DOCUMENTUM BUSINESS OBJECTS FRAMEWORK........................................................................................................................... 22 Page 2 of 50
Developing Web Services with Documentum OVERVIEW .................................................................................................................................. 22 BUSINESS OBJECTS IN PERSPECTIVE ........................................................................................... 23 DOCUMENTUM BUSINESS OBJECTS (DBO) DEFINED ................................................................. 24 APPENDIX C: EXPOSING BOF SERVICES AS WEB SERVICES .................................. 26 OVERVIEW .................................................................................................................................. 26 CONNECTION SERVICE................................................................................................................ 27 Functionality .......................................................................................................................... 27 Implementation....................................................................................................................... 27 Client ...................................................................................................................................... 28 DOCBASE SERVICE ..................................................................................................................... 29 Functionality .......................................................................................................................... 29 Implementation....................................................................................................................... 29 Client ...................................................................................................................................... 31 INBOX SERVICE .......................................................................................................................... 31 Functionality .......................................................................................................................... 31 Implementation....................................................................................................................... 31 Client ...................................................................................................................................... 32 APPENDIX D: USING BOF WITH BEA WEBLOGIC WORKSHOP AND .NET........... 33 DEFINING THE BOF SERVICE ..................................................................................................... 33 DEFINING THE CONNECTION WEB SERVICE ............................................................................ 33 DEFINING THE INBOX WEB SERVICE ....................................................................................... 36 BUILDING THE INBOX CLIENT APPLICATION USING VB.NET ..................................................... 43
Page 3 of 50
Introduction
Enterprise Content Management (ECM) is one of the most important technology areas today. Content comes in many forms, but often represents rich business assets, such as contracts, product information, reports that need to flow across both internal and external business systems and delivered in many different ways. ECM is now recognized more as an underlying platform upon which many types of Content Rich Applications are built. For example, e-learning systems, contract management applications, and portal applications are just a few of the types of Content Rich Applications that utilize ECM. Both the importance and usage of content and content management outlines the need for a way to easily integrate content and the content rich services across systems. Web Services provide a standard mechanism for integrating business logic across the Internet. Several leading Documentum customers are using Web Services with the Documentum platform as an integral part of their ECM architectures.
Industry Momentum
Web Services have gained huge industry momentum, and Documentum is participating with other technology leaders on the development of the standards that form the foundation of Web Services. Documentum is a sponsor of OASIS, a member of W3C, and a member of WS-I and is participating in the Web Services work in these organizations.
Page 4 of 50
Developing Web Services with Documentum Unified content services, our core functionality, refers to not only our robust repository and library services (including security workflow, version control, and so on) but also our more advanced capabilities, such as content intelligence, and rich media management.
Figure 1: Documentum ECM Platform
Industry Solutions Content Applications
For Documentum developers, this functionality is exposed as a common set of APIs and standards-based components, or developer services. Developers can easily leverage this to build customized solutions. A wide variety of content applications are built on Documentum and are designed to meet a wide range of business needs.
Documentum packages its broad set of capabilities into a set of packaged solutions, or Editions, that address specific Unified Content Services content management areas. These packaged solutions provide a convenient way to determine which products you need to meet a particular objective, such as publishing content to the Web, managing rich media, controlling compliance documentation, or enabling enterprise collaboration. To address the business needs in specific industries, Documentum provides industry solutions, which combine Documentum products, partner products, and focused professional services.
h sh
Bind
Page 5 of 50
Developing Web Services with Documentum The current generally accepted implementation of a Web Services contract is defined using WSDL; published in a service registry (UDDI); and invoked over HTTP using SOAP, using XML as the format for data transmission.
Either mechanism will work with Web Services that access Documentum components. Many of the development tools today like, Visual Basic .NET, are WSDL aware. They can use the information in a WSDL file to display lists of functions and their signatures to programmers and automatically create the client stubs to invoke and call the SOAP interface.
Page 6 of 50
Developing Web Services with Documentum More information on Web Services can be found at: www.webservices.org www.uddi.org www.oasis.org
BOF Example
For example, a BOF service could advertise its location so it can be found from remote locations across the Internet. One Web Services standard component, UDDI, provides the ability to register a service for discovery. Once the remote computer locates where the service is using UDDI, it then needs to send a remote function call to the service. Calling a function to execute
Page 7 of 50
Developing Web Services with Documentum on a remote computer involves sending parameters and retrieving results from the remote function. Web Services uses a new HTTP over XML protocol called SOAP (Simple Object Access Protocol). Unlike the binary protocols used with RPC and RMI, which are also remote function calling protocols, SOAP uses XML and HTTP to transfer parameters and return results in the form of SOAP Envelopes. The SOAP Envelopes were designed so that they can even carry content, like other XML files and binary Word documents, Pictures, etc.
Browser
P OA S
Web Server
DFC
DBOF
Page 8 of 50
For each of these roles, Web Services may be accessed at multiple levels, either within an enterprise, across the extended enterprise with partners and suppliers or as generally accessible Web Services over the Internet. Generally, most enterprises will not freely publish their core content management services over the Internet unless that is their actual business model, but will leverage services to rapidly integrate their applications across enterprise systems, and extend functionality to their extended enterprise (customers, partners, suppliers) where appropriate. As Web Services become more the norm for software deployment and services (e.g., pay-per-usage models), corporations will begin to leverage external services for components of their applications.
Portals
The portal is one very good example of exposing content management components. The enterprise portal is becoming the dashboard of the enterprise. Companies no longer want to deal with multiple application front-end interfaces for their employees. Content management is central to a portal in two respects: 1. Enabling employees, partners, and customers to participate in content management applications through one seamless interface 2. Powering portals with accurate content Exposing enterprise content management components as services enables portal builders to rapidly include content management capabilities in the various enterprise portals. This can be accomplished in two ways: Using Web Services below the Portlet UI to call to functions in the Content Management System
Page 9 of 50
Developing Web Services with Documentum Expose Portlets themselves (UI and Business Logic) as Web Services. The WSRP (Web Services for Remote Portlets) technical committee in OASIS is working on a standard for this approach. Exposing these Portlets as Web Services allows for more intelligence within the portal. Instead of having multiple disconnected components, the components can interact through the published interface. For example, for a customer service portal, a sales support person may look up a customer name through a Portlet into the CRM system, while the browse Portlet to the content management system automatically updates the contract view to show contracts just for that customer.
Corporations
Corporations will also build Web Services to expose their in-house applications both within the enterprise and to external partners. Exposing services will be done using standard interfaces, such as a RosettaNet Partner Interface Processes (PIPs), or by agreed-upon interfaces between partners. One of the PIPS (2A9) is a good example of a content-based service that would be exposed by a corporation to their partners. This PIP is used in the semi-conductor industry and allows for companies to search across partners for information on available components that meet certain criteria. Another example might be a financial services company that would like to provide a new offering to some of its value-added customers by providing access from their portal to certain subscribed research reports.
Page 10 of 50
Developing Web Services with Documentum would like this particular document transformed from X to Y and it would automatically find a service that offers this and invoke the transformation.
Page 11 of 50
Developing Developing Web Services Web Services 1. WSDL 1. WSDL 2. SOAP/Java 2. SOAP/Java Stub Stub
Apache
BEA Microsoft
IBM
Oracle
Sun
Web Services Server Stub Web Services Compatible Layer Web Services Compatible Layer DFC 4.x DFC 5.x
1. The first layer is DFC 4.x or DFC 5.x. DFC provides a rich API to develop a Web Service and is described in more detail in the Documentum DFC-based Web Services section. 2. The next layer is the actual implementation of your service. In Documentum 4.x, this will contain the business logic of your service implemented using DFC. In Documentum 5.x this layer will be very thin, if present at all, because Documentum 5 allows you to encapsulate business logic using the new Business Object Framework. 3. The third layer is the actual binding of your service to SOAP, and the WSDL interfaces. As we already mentioned there are many toolkits that provide the ability to automatically create the SOAP server stubs and WSDL files. Some of these are listed in the upper layer of the diagram.
Page 12 of 50
Future Intrinsic Objects Future Intrinsic Objects Operations Workflow Validation Virtual Document
Core DFC Layer Object oriented access to Server API Layer DBO Framework DBO Framework fc.client
Session Manager Session Manager Session Pool Session Pool BO Registry (DBOR) BO Registry (DBOR)
fc.client
The DFC provides a rich set of classes and interfaces that establishes an object-oriented framework and API with which to perform Documentum Repository operations. You can use DFC in any of the following ways: Access Documentum functionality from within one of your companys enterprise applications. For example, your corporate purchasing application can retrieve a contract from your Documentum system. Customize or extend Documentum products like Documentum Desktop or WDK. For example, you can modify the Documentum Desktop functionality to implement one of your companys business rules. Write a method or procedure for Content Server to execute as part of a workflow or document lifecycle. For example, the procedure that runs when you promote an XML document might apply a transform to it and start a workflow to subject the transformed document to a predefined business process. The Documentum Content Server Fundamentals manual provides a conceptual explanation of the capabilities of Content Server and how they work. DFC provides a framework for accessing those capabilities. Using this framework makes your code much more likely to survive future architectural changes in the Documentum system. The core of DFC is a set of Java classes, but it includes other elements as well:
Page 13 of 50
Developing Web Services with Documentum A collection of DLLs to provide the DFC functionality. A type library for accessing DFC via COM from Visual Basic or Visual C++. A set of C++ wrapper classes that hide many details of the DFC/COM interface when you access DFC through the Microsoft foundation classes (MFC) framework.
Whenever writing programs that access the Documentum Repository, the best approach is to use Documentum DFC. This API provides an object-oriented framework for programmatic access and control of content. DFC encapsulates and abstracts the features and details of advanced session management, transaction processing, XML parsing and transformation, and a myriad of necessary features described in the official DFC documentation.
Client
COM SOAP
DFC
Page 14 of 50
Developing Web Services with Documentum 1. A standalone client application calls a service method through a local SOAP client request interface. 2. The SOAP client wraps these calls into a SOAP Message. 3. The SOAP Message is sent to the Web Service interface and the SOAP Message is unpacked. 4. The Web Service calls the associated server method with the parameters extracted from the SOAP Envelope. 5. The method performs any necessary Documentum Repository processing and passes the results back to the Web Service. 6. The Web Service wraps the results into another SOAP Message and sends the results back to the client. 7. The client presents the response to the user. Examples of the services created are as follows: Service Session oriented services Basic Library services Query services Business Policy services Workflow services Security services Business specific services Description of Service Methods Log in, log out, etc. Check in, check out, import, export, etc. Basic and Advanced searching using DQL Promote, demote, suspend, resume Start workflow, halt workflow, send to distribution list, get task, reassign task, etc. User and group administration Methods that automate their business processes
This is just an example of one of many possible applications of Web Services on the Documentum Platform. We have not yet begun to fully realize the true potential of this powerful combination. DFC 4.x vs DFC 5.x Documentum 5 introduces the Business Objects Framework. In the example above, the customer leveraged EJBs to create their services using the library service API in DFC 4.x. In 5.x, it is now possible to encapsulate the business logic at a lower level within the DFC using the BOF. The BOF also provides more advanced session management and transaction processing. For example, a BOF service can perform cross-Docbase queries previously not available. Another feature of BOF is the support for cross-Docbase transaction processing. This allows a single managed transaction to be started on several Docbases and committed or rolled back if needed. Therefore, with Documentum 5, it has become easier to add business objects to content applications and access them through Web Services.
Page 15 of 50
Developing Web Services with Documentum Some of the advantages of DFC 5 version over DFC 4.2 for Web Services are the following: A BOF service implemented with DFC 5 conceptually and logically matches a Web Service: Both represent a functional component of server side business logic. To expose a BOF service as a Web Service only a thin wrapper is required to adapt to the Web Service runtime environment. BOF 5 provides a session manager that optimizes the session resource utilization for connection oriented Web Services. BOF allows the reuse of business logic more easily because it requires a standardization of how to represent business logic. The approach is the same as when trying to represent business logic as a Web Service. Existing BOF services can be exposed as Web Services. The Documentum Business Object Registry (DBOR) allows dynamic changing of the implementation of a service by configuration. Using BOF enables special applications, such as JSP applications that are not Web Services enabled (and where Web Services are not efficient), to use the same business logic components. DFC 5 has a new logging mechanism that enables application specific logging in an application server.
See "Appendix B: Introduction to Documentum Business Objects Framework" for a more detailed description of BOF.
Session management
Overview
To be able to use Web Services with Documentum, some kind of session management is required. Session management is mainly used for performance reasons. In an application based on Web Services typically the following happens: 1. Start application 2. Login 3. Send a series of requests with corresponding results 4. Disconnect Page 16 of 50
Developing Web Services with Documentum 5. Stop application This means that once the user is logged in the application logic would like to be able to use a session until the user disconnects. It would not be practical to have the user log in for every request. Even worse, it would not be practical to not to use user authentication at all as a means of solving this login dilemma. There are several possible solutions listed below, each with pros and cons. The Session Manager is provided as a mechanism to solve this issue.
Disadvantages:
This approach may work well when there are only very few messages sent to the server. For example, a user wants to upload something and then disconnect. Otherwise, it is not recommended to use this approach mainly for security and performance reasons.
Ticketed Login
Documentum servers can generate a temporary password called a ticket which can be used only once. This can be generated only for super users and every user currently logged in, allowing the super user (or a service connected as a super user) to act as a proxy for the specified user. The approach used here is that when the first SOAP message is sent the message contains normal user name and password provided by the user. When the first service call is made, the service requests that the server generates a login ticket and sends it back with the result message. The client then retrieves the ticket from the response and uses it in lieu of the password when establishing a new session with the Repository. Advantages: Better security than sending plain password because a ticket can only be used once. Ticket times out Pollutes request and response message (could be fixed by passing ticket in the SOAP header) Disadvantages
Page 17 of 50
Developing Web Services with Documentum Web Service has to connect to the Docbase with every message (time expensive operation)
Disadvantages:
With Documentum 5 the session manager provides additional scalability that releases sessions not used for a while and caches sessions where required. With Documentum 4.2 a connectionoriented approach was supported but the programming model was dependant on the session pooling settings - either the Docbase session was released at the end of the program only once, or it is released after every service call.
EJB Environment
Web Service Toolkits like BEA Workshop are based on an EJB environment. Web Services are implemented using stateless session beans. The current version of BOF does not yet fully support this environment but can use a stateful session bean to cache the identity information between service calls. This means the user name and password are stored in an EJB when the connection is established. When a Web Service is invoked the EJB that runs the call requests the user name and password from the session bean and connects to the Documentum server. When the call is done it disconnects and sends back the result. Advantages: User name and password is sent once and then the connection ID is used Fully supports EJB clustering (load balancing, recovery etc.) Can use advanced toolkits like BEA workshop
Page 18 of 50
Developing Web Services with Documentum Disadvantages: Web Service must connect to the Docbase with every message (expensive operation) An EJB enabled version of the session manager will be provided in the future to provide session caching. The question here is to find the right balance between clustering with load distribution and session caching. Both mechanisms provide some kind of scalability with different means. When using a cluster, what is important is the kind of clustering strategy used: round robin for every session vs. random distribution vs. round robin with each call.
Security
Web Services as implemented by major vendors like Microsoft or BEA are not very secure by nature. When using Web Services with Documentum these fundamental security problems still exist but no additional security holes are opened. This means when using Web Services with Documentum, standard security holes of using Web Services exist but once Web Services security gets enhanced a Documentum solution would benefit from this as well. The security problems currently known with Web Services are: Authentication requires sending of user name and password along with the SOAP message SOAP messages are not encrypted unless sent to an SSL port May use HTTPS protocol but weak links still remain after the message has reached the server or client
Secure Web Services are not the reality yet but major vendors and different committees like OASIS are working on it today.
Page 19 of 50
Developing Web Services with Documentum the Axis runtime environment. It also registers the service automatically and a WSDL representation of the service can be generated automatically from the JWS file. Additionally, a sample VB .NET project is provided that implements a Windows based simple inbox tool. A user can display and remove inbox items.
Summary
Web Services extends the reach of the Documentum Content Management platform by making the content management services available across the Internet and providing a vehicle for application-to-application communication with little or no human intervention. Why is Documentum the preferred platform for building Content Applications? Here are just a few reasons: Experience Scalable Proven Platform Rich Set of Content Management Services Open Platform and Development Environment Technology Leadership in XML Full set of Partners Documentum clearly understands the importance of Web Services and the application of Web Services to Content Management. Documentum is playing a leading role participating in the development of the standards that will shape the future and application of Web Services. We will be continuing to address support of Web Services in the Documentum platform. As we have illustrated in this paper, Documentum today provides a rich open platform that enables our customers to fully leverage Web Services. In Documentum 5 we have addressed the fundamental requirement of Web Services by allowing our customers to easily encapsulate their business logic in the core platform. Moving forward Documentum will provide some out of the box services and will continue to allow our customers to develop and leverage our open platform.
Page 20 of 50
Many of these tools have comprehensive tutorials, which are extremely beneficial in getting a base understanding of Web Services development. Some Web Services require an application server or servlet container. If you do not have access to an application server, download and install the Apache Tomcat Servlet container. Tomcat is free and can be found at: http://java.sun.com/products/jsp/tomcat/. If you choose to use JWSDP as your development tool, a copy of Tomcat is provided as part of the installation of the tool. There are also tools to develop raw SOAP, WSDL, and UDDI. This approach can be more flexible, but more code is often required. So it is important to choose a tool that you are comfortable using.
Page 21 of 50
Overview
BOF is part of the DFC library and consists of several Java classes and interfaces for constructing and running Documentum Business Objects (DBO). There are two types of Documentum Business Objects, type-based business objects, and service-based business objects. A type-based business object can extend a Documentum Server persistent object type (e.g. "com_accelera_catalog" or "com_accelera_autonumber" might extend "dm_document") and extend its capabilities by providing new methods for those types (actually, new user defined Java classes) and allowing overriding of existing methods, like checkin() and checkout(). A service-based business object provides methods that perform more generalized procedures that are not usually bound to a specific object type or even Docbase. The specific business logic within the business objects is implemented using the standard DFC framework allowing developers to implement a new DBO without a steep learning curve. Since BOF objects are based on the Documentum Foundation Classes (DFC), the developer can maintain a high degree of compatibility with existing DFC applications. Figure 7: DFC Provides DBO Framework
Service-based Business Objects
Other Bus. Obj. Other Bus. Obj. Services Services Your Bus. Obj. Your Bus. Obj. Services Services DCTM Sample DCTM Sample Services Services ISubscription ISubscription Services Services Workflow Workflow Services Services
Future Intrinsic Objects Future Intrinsic Objects Operations Workflow Validation Virtual Document
Core DFC Layer Object oriented access to Server API Layer DBO Framework DBO Framework fc.client
Low-Level
Server Access
Page 22 of 50
Presentati on Layer
Generic Components Custom Components Industry / Company specific behavior
Presentation Layer The presentation layer contains components dealing with user interfaces and user interaction. It is used to display content and structured information in a web browser or stand alone application. For example, the presentation layer of a stand alone application could be written in Visual Basic or Java Swing. In a web environment, Documentum WDK would be the choice to present the layout and to manage the flow and sequence of user interactions. The presentation layer consists of commercial or custom UI components that display information in different ways depending on such factors as the user role or their privileges. For most implementations, this layer is highly customized and must be very configurable. The presentation layer relies on the components (business objects) of the business logic layer to implement and enforce the rules and policies of the company.
Business Logic Layer The business logic layer is completely independent of visualization and of the toolkit used to display information. It provides application specific generalization as a layer of abstraction
Page 23 of 50
Developing Web Services with Documentum and implements the customer specific business rules and policies. It is based on a component object model with components shared between different application areas. In most cases, the policies and procedures of a given company are not very likely to change greatly so the business object components implement those policies and procedures. Alternatively, if a policy or procedure does change, the implementer can just modify the corresponding business logic component and all the dependent applications and components will automatically conform to the new policy. One of the major improvements of Document 5 is the ability to support both stateful and stateless Docbase sessions. This allows the business object to focus on the business rules and to leave the session management and transaction handling to the framework. Data Layer The data layer is used by the business logic layer to permanently store the state of the objects, content, and other information. Central to the data layer is one or more data servers that house the stored state. The Documentum implementation of the data layer is comprised of one or more Content Servers with their associated RDBMS servers. The data layer is logically separated into two useful parts, the Content and Schema Layer and the Core Content Management Services Layer. Content and Data Schema Layer The data schema layer defines the content object hierarchy as well as the physical schema used to store the aggregated business data. Creation and management of the schema can be achieved using the Documentum Administrator utility or directly by using DFC calls. The business objects in the business object layer provide a logical abstraction of the details of the DFC interfaces to the content and data schema. Therefore, the business objects can manipulate content and its metadata on behalf of the presentation layer applications without relying on those applications being aware of how the data and content is physically organized. Separation of the schema from the business logic layer and the database layer promotes the ability to scale to a different database and continue to use the business objects and applications unmodified. Core Content Management Services Layer The core content management services layer provides the library services, process automation, and content authentication to the business objects. This layer is implemented by the Documentum Content Server. It provides the basic building blocks to construct higherlevel business logic components.
Page 24 of 50
Developing Web Services with Documentum Type Based Objects (TBO) Type based objects are implemented as classes that extend basic persistent DFC types such as DfDocument, DfSysObject, DfPersistentObject, DfFolder, etc. They allow you to encapsulate business logic that is specific to a particular Docbase object type. There are two main reasons for creating a TBO: 1. To provide a new behavior for existing or new object types. For instance, a developer may decide to add getter and setter methods for object specific attributes or add new methods like adding a Product to a Catalog TBO. 2. Customizing low-level operations to enforce data validations, referential integrity and object specific business rules. For instance, a developer may decide to override the save() and checkin() methods to be able to validate data before saving them in the persistent storage. Service Based Objects (SBO) Service based objects are not tied to a specific Documentum object type. They are generalized objects that provide a specific service that may operate on different Documentum object types or other business objects. An example of a service-based object is the Documentum IInbox service that retrieves items from a user's inbox and may also perform a number of other operations such as remove item, forward item, etc. Such an object would not be tied to a specific object type. Your SBOs are built using public BOF interfaces and implementation classes supplied by DFC. Service and session manager factory methods are also provided by DFC.
Page 25 of 50
Of course, we could add additional services that would all use the basic functionality of the two helper services. New services can be plugged in as needed. The following diagram shows what components are required and how they relate to each other:
Figure 9: Required Components
Servlet Container Servlet Container AXIS Servlet Connection Service Connection Service Inbox Service Inbox Service IInbox IInbox DFC DFC BOF BOF Web Services Docbase Service Layer Docbase Service IDocbase IDocbase Business Objects Layer
Page 26 of 50
Developing Web Services with Documentum The Apache AXIS Servlet is running in a Servlet container such as Apache Tomcat. Three Java Web Service (JWS) files (ConnectionService, InboxService, DocbaseService) are deployed and registered into the Axis Servlet repository to provide an adapter to the BOF Inbox and Docbase services. Using JWS makes deployment very easy. JWS files just need to be copied into the web application folder of the Axis Servlet and they are automatically registered. These JWS services then call the applicable BOF service interface. The main benefits of using JWS to provide SOAP wrappers on top of BOF services are: Service registration: Services become available on a web server Selective exposure of service method: BOF service methods may be shielded from Web Service access Parameter conversion: BOF services usually define DFC based method parameters. In a SOAP environment, it is more convenient to use basic type such a String, integer, etc. Therefore it is often required for example to convert a Documentum ID of type IDfId into a string and vice versa WSDL generation: The JWS files can be easily converted into WSDL files
The subsequent sections describe the functionality that each of the three services provides.
Connection Service
Functionality
The connection service is a simple helper service (without BOF implementation) that maintains a connection across multiple service calls. When a connection is opened a unique connection ID string is returned to the client. With every subsequent service call, this connection string must be maintained until the connection is explicitly closed. If the client forgets to call the close() method, the connection will eventually time out. The connection service maintains a static list that stores a BOF session manager for each unique connection ID. This takes advantage of the basic session pooling provided by BOF and therefore provides optimized performance.
Implementation
The following code shows how the connection service is implemented. It is implemented as ConnectionService.jws (JWS file is a normal Java class file where the extension is changed from .java to .jws) and it is deployed for example into the <tomcat_home>/webapps/axis directory:
Page 27 of 50
This service just provides two methods that allow opening and closing of a connection. The open() method returns the unique connection ID string, which is later used to close() the connection. The ConnectionServiceManager.java is a static helper class that generates a unique ID and stores a BOF session manager instance associated with each connection. It also ensures that the session times out and returns the session back to the session pool. There are other approaches that provide the same functionality (e.g. using servlet sessions), but for convenience, we provide the following implementation:
ConnectionServiceManager.java
public static String open() throws DfException { String id = generateUniqueId(); sMgrList.put(id, DFClient.getLocalClient().newSessionManager()); return id; } public static void close(String connection) { sMgrList.remove(connection); }
The open method just stores the generated ID (code not shown) in a hashtable and creates a new instance of a session manager. When the connection is closed, the hashtable entry for the given connection is removed.
Client
Once the service JWS file is deployed into the AXIS Servlet, a WSDL file can be generated using the standard AXIS utility Java2WSDL. The client interface can then be generated e.g. using .NET. To illustrate how to call the Web Service we use Java and the AXIS toolkit. The following code shows how the connection can be opened and closed. Page 28 of 50
Service service = new Service(); Call call = (Call) service.createCall(); call.setTargetEndpointAddress( baseUrl+"ConnectionService.jws" ); call.setOperationName("open"); call.setReturnType( XMLType.XSD_STRING ); String connection = (String)call.invoke(new Object[]{});
First, a service is created and a call is constructed that sets the target service, the operation and the return type. When the service is invoked, the connection string is returned. This connection is required for all subsequent method calls including the close() method. The baseUrl variable contains the address of the web server when the service is running, for example "http://myhost/axis/".
call = (Call) service.createCall(); call.setTargetEndpointAddress(baseUrl+"ConnectionService.jws"); call.setOperationName("close"); call.addParameter( "connection", XMLType.XSD_STRING, ParameterMode.IN ); call.setReturnType( XMLType.XSD_ANY ); Object[] params = new Object[] {connection}; call.invoke( params );
The next call closes an open connection. We pass the connection string a parameter but the service invocation does not return a result.
Docbase Service
Functionality
The Docbase service is a second helper service that provides basic Docbase handling functionality like retrieval of a list of valid Docbases, setting identities, and removing identities. To be able to use the Docbase service a connection must be established. The Docbase service is independent of DFC Docbase sessions since stateless sessions are managed by the BOF framework.
Implementation
The Docbase service is implemented as a BOF service with the interface IDocbase and requires a JWS service that is deployed to the AXIS Servlet as DocbaseService.jws. The Docbase BOF service is implemented as follows:
Page 29 of 50
It defines a method to retrieve all Docbases names known to the Docbroker. This method returns an array of strings for each Docbase name. A second method is for setting an identity for authentication on a given Docbase. Using this mechanism, you can set identities for multiple Docbases. When an identity is cleared, Docbase access to that Docbase is disabled. Before a service like the IInbox service is called, an identity must be set. A JWS file needs to be created to provide an adapter to expose the service as a Web Service. It is also deployed into the AXIS Servlet repository. The following code shows how the DocbaseService JWS is implemented:
public class DocbaseService { public String[] getDocbaseList( String connection ) throws Exception { IDocbase docbaseService = (IDocbase) ConnectionServiceManager.getService( IDocbase.class.getName(), connection); return docbaseService.getDocbaseList(); } public void setIdentity( String connection, String docbase, String user, String password, String domain ) throws Exception { IDocbase docbaseService = (IDocbase) ConnectionServiceManager.getService( IDocbase.class.getName(), connection); docbaseService.setIdentity( docbase, user, password, domain ); } public void clearIdentity(String connection, String docbase) throws Exception { IDocbase docbaseService = (IDocbase) ConnectionServiceManager.getService( IDocbase.class.getName(), connection); docbaseService.clearIdentity(docbase); }
Each method gets the connection string as a parameter plus additional parameters if required. It then calls the corresponding BOF service and returns the result if applicable. In addition, the connection session manager is used to provide a convenience method to pass the connection and the service name and it then instantiates the service. Page 30 of 50
Client
The following Java sample code shows how to use the AXIS client toolkit to call the Docbase service. We assume that we already have an open connection with the connection ID stored in the "connection" variable. The following code calls the DocBroker list and gets back an array of string names of Docbases that project to this DocBroker:
call = (Call) service.createCall(); call.setTargetEndpointAddress(baseUrl+"DocbaseService.jws"); call.setOperationName("getDocbaseList"); call.addParameter( "connection", XMLType.XSD_STRING, ParameterMode.IN ); call.setReturnType( XMLType.SOAP_ARRAY ); String[] strDocbases = (String[])call.invoke( new Object[]{connection} );
Inbox Service
Functionality
The IInbox service is a sample service that provides simple Documentum inbox manipulation. It allows itemizing of the user's inbox items, to display item details, and to remove an item. This service could be any other BOF based service that you may want to add that is provided by Documentum or Documentums partners. Typical BOF services would probably be more complex but the IInbox service shows the basic mechanism.
Implementation
The Inbox service is implemented as a BOF service with the interface IInbox and requires a JWS service that is deployed to the AXIS servlet as InboxService.jws. The Docbase BOF service is implemented as follows:
public interface Iinbox extends IDfService { IDfList getList(String docbase) throws DfException; IDfList getDetail(IDfId item, String attributes) throws DfException; void remove(IDfId item) throws DfException;
It defines a method to retrieve all items of the current users inbox. The result is returned as a list of IDfId objects. Each item can then be looked up using the getDetail() method. This method allows you to specify a comma separated string to indicate what attributes you are interested in. This method returns an IDfList of values. Finally, the remove() method removes an Inbox item. The IInbox service is implemented in a Java class, named Inbox, which is mapped to the interface using the business object registry (DBOR) provided by BOF.
Page 31 of 50
Developing Web Services with Documentum To provide an adapter to expose the service as a Web Service a JWS file must be created that is deployed into the AXIS servlet repository. The following code shows how some of the InboxService.jws JWS is implemented (for simplicity, only one method is shown):
public class InboxService { public String[] getList(String connection, String docbase) throws Exception { IInbox inboxService = (IInbox) ConnectionServiceManager.getService( IInbox.class.getName(), connection); IDfList list = inboxService.getList(docbase); int count = list.getCount(); String[] result = new String[count]; for (int i = 0; i < count; i++) result[i] = list.getId(i).toString(); } return result;
This example shows the wrapper nature of the JWS file. It uses the connection service manager to instantiate a service that contains the right BOF session manager and then just calls this service. The service returns an IDfList of IDfId objects, and since they are not very suitable for Web Services, the list is first converted into a string array if ID strings and then returned.
Client
The following sample code shows a Java client using the AXIS toolkit. It assumes that the connection is established (using the connection service) and that an identity is defined (using Docbase service). Then, calling the getList() method returns an array of strings. Each string represents the name of a Docbase.
call = (Call) service.createCall(); call.setTargetEndpointAddress(baseUrl+"InboxService.jws"); call.setOperationName("getList"); call.addParameter( "connection", XMLType.XSD_STRING, ParameterMode.IN ); call.addParameter( "docbase", XMLType.XSD_STRING, ParameterMode.IN ); call.setReturnType( XMLType.SOAP_ARRAY ); String[] items = (String[])call.invoke(new Object[]{connection, docbase});
Page 32 of 50
The getList() method retrieves all IDs of the current users inbox items. For each item, the getDetail() method can be called to obtain the details of the item, such as task name and priority. The remove() method simply removes the specified item from the inbox. Please note that this service uses Documentum specific data types such as IDfId, which is used to pass Documentum specific data types.
Page 33 of 50
Developing Web Services with Documentum To achieve these two objectives, an EJB is created to store connections with associated identities. In addition, a Web Service is needed to allow opening a connection, setting identities, and closing the connection. Figure 10 shows the Connection Web Service that is created using BEA WebLogic Workshop:
Figure 10: Connection Web Service Design View
All of the operations of the Web Service are graphically displayed on the left side of the right pane. Clicking on an operation allows it to be implemented or modified. The connection control on the right side allows caching of identities. It is implemented as an EJB, as indicated by the EJB icon. The Connection service is basically a wrapper on top of the EJB. It exposes all operations except getIdentity. This is done purposefully to prohibit access to this information from a Web Service. In order to use the Connection service, the application must first call open to get a unique connection ID. From then on, all operations must provide this connection ID. The next screenshot shows the implementation of the open operation. It simply calls the corresponding method in the EJB control and returns the string result.
Page 34 of 50
The Connection service must be created and registered once. Then other Web Services can be created for each BOF business object and the Connection service is used by all of them.
Page 35 of 50
The operations of the InboxService.jws (JWS = Java Web Service) are displayed. In addition, it shows the same methods that the BOF service exposes. The next step is to add a control that is implemented as an EJB that uses cache identities to create Docbase connections. The purpose of this control is to provide session management for Web Services. This is required for performance and security reasons. Since the application in this example first connects and then performs several operations on the inbox, the user identity must be cached on the application server. The session could be reused if the user sends several requests within a short period of time.
Page 36 of 50
Developing Web Services with Documentum Clicking the addControl button allows you to define the connection control mentioned previously using the Add EJB Control dialog as shown in Figure 13.
Figure 13: Add EJB Control dialog
Here an EJB called ConnectionManager is selected. This EJB was already deployed to the WebLogic server. NOTE: This is done once and the control remains registered in Workshop. Figure 14 shows how the control is displayed in the graphical view of Workshop:
Page 37 of 50
Figure 15 shows the implementation of the remove operation. The source code shows up when the operation is clicked:
Page 38 of 50
First, the identity is obtained from the connection manager. The connection ID conn and the item ID item are passed to the remove operation as arguments from the caller using the getIdentity() method. The getIdentity() method returns an IdentityInfo object info. Next, the IInbox BOF service is instantiated using the Connection.getService() method. Then the IInbox.remove() method is called and thats it. WebLogic Workshop allows testing the Web Service just created and also allows source-level debugging of the service. Figure 16 shows the InboxService test page that provides a mechanism of testing all operations provided by the service:
Page 39 of 50
Figure 17 shows how the getList() method is tested. Figure 16 shows how the connection ID and the Docbase name are entered. The connection ID was provided by the connection open() method. When the getList button is clicked, the getList() method is invoked and produces the <ArrayOfString> list as shown:
Page 40 of 50
Once the Web Service is implemented and tested the WSDL is generated to describe the service for the client applications. Figure 18 shows the InboxService Generate WSDL from JWS context menu option.
Page 41 of 50
This is also required for the Connection service as shown in Figure 19.
Page 42 of 50
When the application is started the login dialog is called first. All of this is designed using VB.NET.
Page 43 of 50
The Web Services are registered as WebReferences using the Add Web Reference dialog shown in Figure 22:
Page 44 of 50
Enter the URL of the Web Service and then specify WSDL after the question mark. Then click the Add Reference button. The Web Service is registered and it shows up in the solution explorer window. In VB the service is now known as ConnectionSvc as shown in Figure 23.
Page 45 of 50
Figure 24 shows how the service can be called from the VB implementation:
Page 46 of 50
The global variable conn is defined the type as returned by ConnectionSvc.Connection(). When the form is loaded, the conn.open() method is called, which returns the connection ID. This ID is then passed to the login dialog. For each service there is a global variable in the VB application and we just call the corresponding member functions. Using the WSDL definitions of the services, VB .NET can automatically list all methods that this service exposes as shown in Figure 25:
Page 47 of 50
Once the VB code is implemented we can start the application. First the login dialog is displayed:
Figure 26: Docbase Login dialog
Page 48 of 50
Page 49 of 50
Page 50 of 50