Core Development
· What are Document Definitions?

Web Services
· How is Session State maintained over Web Services?
· Using (insert language) I am able to authenticate, but subsequent calls using other service managers are failing. Why?
· How does Content Upload/Download work over Web Services?

What features does the Client Java Content DB Development Kit library offer over the regular Java bindings?

The client Java Content DB Development Kit library (cdb-devkit-client.jar) that supplements the standard Content DB Java Web Service bindings/stubs (content-ws-client.jar) was introduced to allow client code to run either in-process or remotely without having to make significant (or any) code changes. To achieve this, Oracle provides proxy classes that:

• hide from developers the DAV server dependency for content upload/download

// Java Example Code (using client Java Content DB Development Kit):

FileManager fileM = ...

// source content stream
InputStream is = ...

Item docDef = fileM.createDocumentDefinition(    
  new NamedValue[] {
    ClientUtils.newNamedValue(Attributes.NAME, "test.doc"),

    // A client using standard auto-generated Web Service bindings CANNOT 
    // utilize Options.CONTENTSTREAM in a createDocument[Definition]/updateDocument
    // call. Instead, they must make a PUT call to the Content DB DAV 
    // Server using a HTTP client and use the JSESSIONID (session state) as
    // the Web Services.

    // In this example, the client uses the Java Content DB Development Kit.
    // This means the DAV call is automatically performed by the underlying proxy 
    // class and hence Options.CONTENTSTREAM is valid.
    ClientUtils.newNamedValue(Options.CONTENTSTREAM, is),
  }, null);

• hide from developers the session (cookie) state management/tracking requirements.
• implement the same interface as the Web Service bindings and in-process FDK classes

Back to top

What features does the C# .NET Development Kit offer over auto-generated C# bindings?

The C# .NET Development Kit provides significant benefits over the token generated stubs that Visual Studio is capable of creating from the Content DB WSDL. Using similar techniques to the client Java Development Kit, it hides DAV server dependency for content upload/download, manages session state across the seperate managers, and most importantly correctly deserializes FdkExceptions from SOAP Faults.

Back to top

What are Document Definitions?

DocumentDefinition items are temporary content objects in the repository that may be used as a content source for FileManager createDocument and updateDocument calls. A DocumentDefinition item gets automatically freed/cleaned-up upon its expiration. Their primary benefit is that they allow a createDocument/updateDocument operation to be retried (in the event of a recoverable exception such as missing metadata) without requiring the content to be re-uploaded to the repository.

// C# Example Code:

FileManager fileM = ...

// We need the URL of the returned DocumentDefinition to be able
// to perform the HTTP PUT to this destination to upload the content
AttributeRequest ar1 = new AttributeRequest();
ar1.setAttributeName("URL");

// Name of the DocumentDefinition
NamedValue nv1 = new NamedValue();
nv1.setName("NAME");
nv1.setValue("sample_iso_8859_1_english.txt");

// character set of content to be uploaded 
// (applicable to non-binary text documents)
NamedValue nv2 = new NamedValue();
nv2.setName("DOCUMENT_CHARACTER_SET");
nv2.setValue("ISO-8859-1");

// language of document (to assist Oracle Text)
NamedValue nv3 = new NamedValue();
nv3.setName("DOCUMENT_LANGUAGE");
nv3.setValue("ENGLISH");

// create the DocumentDefinition
Item docDef = fileM.createDocumentDefinition(    
  new NamedValue[] { nv1, nv2, nv3 },
  new AttributeRequest[] { ar1 }
);

// Next, retrieve the URL from the returned document definition.
// Use a regular HTTP client to perform the HTTP PUT to the destination 
// URL supplying the source document stream to upload the actual content.
// Note: Java clients using the Content DB Development Kit could have supplied
// the content stream inline using an Options.CONTENTSTREAM NamedValue.

Back to top

How is Session State maintained over Web Services?

Session Management in a stateful Web Service (using HTTP for the SOAP transport binding) is typically achieved using either SOAP headers or HTTP cookies. The Oracle Content DB Web Services use the HTTP cookies method, and thus, a client using the Oracle Content DB Web Services must support HTTP cookies. Session authentication/establishment for the Oracle Content DB Web Services is performed by either the RemoteLoginManager, or through S2S (ServiceToServiceLoginManager or S2S servlet). When a client successfully authenticates using the appropriate login operation, a 'set-cookie' directive is returned with the response (the cookie name is JSESSIONID - the standard OC4J Session Cookie). Any subsequent Web Service requests by the client must include this cookie. Failure to include this cookie will result in a SOAP Fault being returned, containing an FdkException with the error code "ORACLE.FDK.AccessDenied." The Oracle Content DB Web Services do not currently use SOAP Headers because not all clients support them. Additionally, the session cookie is required in order to upload/download content through our WebDAV server (which does not support SOAP headers).

Back to top

Using (insert language) I am able to authenticate, but subsequent calls using other service managers are failing. Why?

Each Oracle Content DB Web Service (Manager), has a unique end-point address. Most programming languages when generating stubs for these Web Services will treat each stub as a separate entity with its own encapsulated session state. However, the stubs must share a common session state (i.e. use the same cookie[s]) for web service calls to Oracle Content DB. The client Java Content DB Development Kit and C# .NET Development Kit automatically handles session management/tracking out-of-the-box through its proxy classes. Raw generated bindings (be it Java, C#, etc) do not.

C# sample code is provided below demonstrating explicit setting and sharing of a CookieContainer item (the C# devkit proxy classes take care of this automatically):

// C# Example Code:

// end-point constants
string MGR_FILE         = "FileManager";
string MGR_REMOTELOGIN  = "RemoteLoginManager";

// connection details
string baseWSURL = "http://host:7777/content/ws/";
string username = "matt";
string password = "welcome1";

// cookie container to be shared by all services/managers
System.Net.CookieContainer sessionCookies = new CookieContainer();

RemoteLoginManager rlM = new RemoteLoginManager();
rlM.CookieContainer = sessionCookies;
rlM.Url = baseWSURL + MGR_REMOTELOGIN;

// authenticate
NamedValue[] result = rlM.login(username, password, null, null);  

FileManager fileM = new FileManager();
// utilize cookie container (populated initially by RemoteLoginManager login call)
fileM.CookieContainer = sessionCookies;
fileM.Url = baseWSURL + MGR_FILE;

// lookup existing Workspace item
Item marketingWorkspace = fileM.resolvePath("/xxx/Marketing", null);

Back to top

How does Content Upload/Download work over Web Services?

During the course of Oracle Content DB development, we looked at some of the major Web Services client development platforms and their support for various Web Services standards, including support for attachments. A number of clients either did not support attachments, or had key functionality missing such as the ability to support MIME attachments. Because our Web Services are based on HTTP and require client-side cookie support, we are able to provide content upload and download through the Oracle Content DB WebDAV Server. The WebDAV server must be presented with the same user session cookie that is established through the RemoteLoginManager or ServiceToServiceLoginManager login operation. The client, once identified by the WebDAV server, only needs to perform a standard HTTP GET or PUT to download or upload content. HTTP PUT calls can also participate in Web Service-initiated transactions; this means that a rollback on the transaction will also reverse any content changes.

Core Item objects, such as Document and Folder objects, provide support for URL and ID_URL attributes, which can be requested as part of the attribute request array parameter. In order to download a document from Oracle Content DB, you initiate an HTTP GET call, supplying the appropriate resource locator value to the WebDAV Server. The URL parameter for a document is derived from the document's folder path and name, whereas the ID_URL parameter for a document is based on the document's unique identifier (ID value). Should a document's location (or name) change, a bookmarked hyperlink based on the ID_URL will continue to function, whereas a URL (folder path) based hyperlink will no longer be valid. Although the ID_URL may seem most suitable to use when providing hyperlinks to documents, keep in mind that this value contains no contextual information that could help users identify the particular file it represents.

Although there are a number of different ways to upload a document to Oracle Content DB, all rely on an HTTP PUT operation being initiated against the WebDAV Server. A PUT call that supplies the WebDAV server with a resource locator that identifies an existing document in the system will result in an attempt to overwrite the destination document's content. This attempt may or may not succeed, depending on the user's security permissions, document lock status, and destination folder policies (such as versioning policy or enforced recordization). The following steps show the preferred approach to uploading a document to Oracle Content DB:

1. Create a DocumentDefinition object using the FileManager createDocumentDefinition operation, specifying a destination filename, along with an Attribute Request for the new DocumentDefinition's URL. Store the ID and URL of the returned DocumentDefinition item.
2. Upload the source document's content by performing an HTTP PUT operation against the WebDAV Server, using the destination URL obtained in the previous step. The DocumentDefinition will now contain the content of the source document.
3. Invoke the FileManager createDocument operation, specifying the DESTINATION_FOLDER and USE_SAVED_DEFINITION options. The value for the USE_SAVED_DEFINTION option should be the ID value obtained from the initial createDocumentDefinition call. Additional options can also be specified, including CATEGORY_DEFINITION, RECORD_DEFINITION, and conflict resolution options such as OVERWRITE or NEWVERSION.

Note: The Java and C# .NET Content DB Development Kits allows a stream to be supplied inline using an Options.CONTENTSTREAM NamedValue to createDocument[Definition]/updateDocument call. The proxy class in-turn will perform the underlying HTTP PUT call to DAV server on the developer's behalf!

Back to top