| Oracle® Content Services Application Developer's Guide 10g Release 1 (10.1.2.2) Part Number B25277-02 |
|
|
View PDF |
| Oracle® Content Services Application Developer's Guide 10g Release 1 (10.1.2.2) Part Number B25277-02 |
|
|
View PDF |
Oracle Content Services Web Services consists of about two hundred operations that can be remotely invoked. Related operations are organized into categories called managers. A manager has its own WSDL file and Java interface in the Web Service Java stubs library.
This chapter describes the following Oracle Content Services Web service managers:
The complete listing of service managers along with their supported operations can be found at the URL http://<host>:<port>/content/ws with <host> and <port> values replaced to reflect that of your own Oracle Content Services 10g instance.
Descriptions of individual operations and the parameters required for each operation are located in the Oracle Content Services Web Services Java API Reference (Javadoc) of the interface of the same name or the class that has implemented that interface.
Descriptions of the XML structure of each of a manager's operations are located in the WSDL file named after the manager at the URL http://<host>:<port>/content/wsdl/<name of manager>.wsdl.
These managers provide operations for manipulating files and folders.
The FileManager provides core document, folder, and link management capabilities.
The FileManager supports the following operations:
Resolve an item based on a supplied path string (the returned Item will be a Document, Link, or Folder)
Resolve an item based on a supplied relative path string and source folder
Check to see whether an item exists based on a supplied absolute path
Check to see whether an item exists based on a supplied relative path string and source folder
Create and return folders in the supplied destination folders
Update a folder
Return (list) items in a given folder, with optional sort criteria
Check to see whether an object with the given name can be created in the given folder
Copy one or more specified items to a given destination folder
Move one or more specified items to a given destination folder
Delete one or more specified items (deleting a folder will delete of all its items)
Create one or more document definitions. (Note: These definitions are created with empty content; to load content, perform an HTTP PUT to the WebDAV Server.)
Create one or more documents, potentially using saved document definitions as source. (Note: These documents are created with empty content; to load content, perform an HTTP PUT to the WebDAV Server.)
Update a document
Create a link to a given item in specified destination folder (links can be made to items of type: Domain, Container, Workspace, Folder, Document, and Family)
Update a link
Check if a given path string contains any link items
Get supported languages
Get supported character sets
Return most recent documents for connected user, with optional sort criteria (the MostRecentDocAgent is responsible for maintaining users' most recent document statistics)
Uncompress supplied items
Get name conflict resolution options
Create documents, document definitions, folders and links
Get a list of supported languages or character sets
|
Note: Content upload/download is handled by standard HTTP PUT/GET, not Web service attachments. |
The TrashManager provides trash folder operations. All workspaces (including personal workspaces) come with a trash folder that, if enabled, stores deleted items.
The TrashManager supports the following operations:
Empty the specified trash folder
Configure the specified trash folder. This includes enabling or disabling it, enabling or disabling the auto-empty feature, and setting the minimum holding period before the trash folder purges itself (when the auto-empty feature is enabled).
The ArchiveManager provides archive operations. When a trash folder is emptied, its contents can be moved to a special area in the repository known as an archive. Each domain has its own archive that is accessible by content administrators.
The ArchiveManager supports the following operations:
Empty an archive
Restore an item from the archive, or make a request to a content admininstrator to restore an item
Configure an archive. An archive can be enabled or disabled, set to automatically empty itself, and have a minimum holding period for its contents.
These managers handle how documents are listed, accessed, and categorized.
The SortManager sets user's default sort preferences for the following tables used by the Oracle Content Services application. These tables are defined in the FdkConstants class in the Web services Java API. These tables include:
fileListingTable
versionHistoryTable
joinableWorkspacesTable
lockedFilesTable
userSearchResultsTable
checkedOutFilesTable
workflowReportTable
virusNamesTable
recentFilesTable
groupMemberList
groupMembers
memberListingTable
rolesTable
securityConfigTable
selectedUsersOrGroupsTable
usersOrGroupsTable
In addition, many Web services operations that return item arrays support setting the sort sequence as part of their operation parameters.
The SortManager supports the following operations:
Set the user's sort preference for the specified table
Obtain the user's primary or secondary sort attribute for the specified table
Obtain the user's primary or secondary sort direction (ascending or decending) for the specified table
Sort an array or a list of items (where the array of items are an attribute of the specified item)
The SearchManager provides the ability to search for documents, with the use of a SearchExpression tree. This is a complex type object that consists of two operands, left operand and right operand, which are associated by a specified operator. Depending on the type of operator, the left and/or right operands may themselves be SearchExpression nodes. This enables one to build a complex SearchExpression tree. The following table describes the operators and supported by SearchExpression:
Table 9-1 Operators Supported by SearchExpression
| Operator | Syntax | Notes and Examples |
|---|---|---|
|
EQUAL GREATER_THAN GREATER_THAN_EQUAL LESS_THAN LESS_THAN_EQUAL NOT_EQUAL IN |
Left operand is the string name of the attribute being compared. Right operand is the value being compared, represented as a String, Integer, Long, or Date. |
Wildcard characters "*" and "?" are supported only for the EQUAL comparison operator so long as comparing an attribute with datatype String. Example:
|
|
CONTAINS |
Left operand must be null, Right operand specifies words or phrases to be found in content of a document. |
Words are specified by spaces, and phrases are enclosed in double quotes ("). Example: |
|
AND |
Left and Right operands must themselves be SearchExpressions |
|
|
OR |
Left and Right operands must themselves be SearchExpressions |
|
|
NOT |
Left operand must be null, Right operand must be a SearchExpression |
|
A Search is invoked by supplying SearchManager's search operation with a SearchExpression tree along with zero or more optional search options.
The SearchManager supports the following operations:
Restrict search to one or more specified folders (including optionally sub-folders)
Include or exclude non-current versions of a versioned document from being searched
Set the start index for the first item in the server's search result array that should be returned. (Default is 1, which means to return all items from the search result array starting from the very first search result)
Limit the number of items returned back to the client from the server's search result array
The LockManager provides operations for working with Locks, which prevent outside changes from occurring on an item that is currently being worked on. The repository will automatically deploy certain types of locks transparently when a caller requests specific types of operations (for example, a checkout call). Certain client applications such as Microsoft Office that have native WebDAV support often will also request a DAV lock during the course of editing a supported document type.
The LockManager supports the following operations:
Acquire a manual lock on one or more items
Release a manual lock on one or more items
Return a list of items locked by the current user that match the specified lock type(s), for example, manual lock or WebDAV lock.
| Lock Type Constants from oracle.ifs.fdk.FdkConstants | Value |
|---|---|
LOCKTYPE_MANUAL |
1 |
LOCKTYPE_CHECKOUT |
2 |
LOCKTYPE_FINALIZED |
3 |
LOCKTYPE_WORKFLOW |
4 |
LOCKTYPE_RECORD |
5 |
LOCKTYPE_FAMILYHASRECORD |
6 |
LOCKTYPE_DAV |
7 |
The VersionManager tracks changes made to an item's content and metadata throughout its lifecycle. Tracking every revision of every document in the system is expensive from a system resources perspective, though potentially a requirement for certain businesses. However, Oracle Content Services allows an administrator to choose the right balance between user requirements, system resources, and performance.
A folder can have the following versioning configuration settings:
Whether manual or automatic version should be applied to items in the folder
If automatic versioning is being used, whether to enforce a limit on the number of revisions maintained
Whether the versioning configuration is final: subfolders cannot override the versioning configuration
Oracle Content Services uses a serial versioning model. The server maintains a single version series for each versioned document. To manually create a new version of a document, the following steps occur:
The author checks out the document.
The server makes a working copy of the latest version (including both content and metadata). This server-resident working copy is accessible only to the user who checked out the document.
A lock is also issued to prevent other authors from checking out the versioned document.
When the author is finished making changes to the working copy, he or she checks in the document.
A new version of the document is created. The new version becomes the latest version of the document, and like any document version, is immutable and cannot be further updated.
The lock acquired at check-out is then released, allowing other users to check-out the document and the working copy object is destroyed.
The VersionManager supports the following operations:
Check out a set of items
Cancel check out for a set of items
Copy a specified version to another folder, to the working copy, or as the latest version
Move a specified version to another directory
Delete a specified version so that it is no longer part of the version histroy
Retrieve an item's versions
Check in a set of items
Update a version-controlled item's attributes (such as version comments, the version label, and the do_not_purge flag)
Make a non version-controlled document versioned
Replace or remove the versioning configuration of a folder
The VirusManager scans and potentially repairs documents for viruses. Oracle Content Services ships a default virus scanning adapter that uses Symantec AntiVirus Scan Engine (SAVSE) using ICAP 1.0.
An asynchronous background agent, VirusScanAgent, regularly polls the virus scanning adapter to determine if a new virus definition build is available. When a new virus definition is detected, the system domain property IFS.DOMAIN.VIRUSSCANNER.LastVirusDefinitionUpdate is modified accordingly.
The scanning process is on-demand. The following events occur when a document is requested:
The system looks at the metadata associated with that document to determine whether a virus scan needs to be performed. Associated with each document is a LAST_SCANNED_DEFINITION_DATE attribute, which tracks the virus definition timestamp that was last used to scan the document. If this attribute is null or older than the LastVirusDefinitionUpdate domain property, then the document's contents are scanned. (Otherwise, the document contents are immediately returned.)
Depending on the result of the scan, the document's contents are either returned to the user if a virus have been detected (or a repair was successful), or else an error is returned and the document is quarantined. The LAST_SCANNED_DEFINITION_DATE is also updated to reflect the new virus definitions that were utilized.
The following events occur when a document is quarantined:
The document's IS_QUARANTINED and QUARANTINED_DATE attributes are updated.
VirusScanAgent receives an event alerting it of the infected document.
The agent attempts to repair quarantined documents that have a REPAIR_ATTEMPTS value less than the domain property IFS.DOMAIN.VIRUSSCANNER.MaxRepairAttempts and LAST_SCAN_DEFINITION_DATE older than the LastVirusDefinitionUpdate domain property.
The agent creates a VirusReport (Category Instance) that is associated with the quarantined document after the repair attempt.
Documents under quarantine have the following properties and behaviors:
Document objects themselves will be unaffected by quarantine status (in particular, metadata can still be viewed or modified)
Contents cannot be opened for read access under any circumstances. Attempts will result in an exception. Contents will remain unreadable even if the anti-virus option is disabled.
Contents may be overwritten.
Documents and their contents may be deleted.
Documents will not have specific infection information available until the VirusScanAgent attempts to repair it.
The VirusManager supports the following operations:
Scan specified items
Attempt to repair specified items
Retrieve the virus report for a specified item that was sent for repair
Retrieve the currently known timestamp of the last virus definition update
The RecordsManager provides a way to define the lengh of time certain documents should be stored, and how to destroy these documents after this length of time, or retention period, has elasped.
This manager provides the following operations:
Create a file plan
Create a record series under the specified file plan
Create a record category under the specified record series or file plan
Create a record folder under a record category
Delete a file plan (the delete will fail if there are record series or record categories under it)
Delete a record series (the delete will fail if there are record categories under it)
Delete a record category (the delete will fail if there are any record folders or records under it)
Delete a record folder (only empty record folders can be deleted)
Update a file plan
Update a record series
Update a record category
Update a record folder
List file plans
List record series under a specified file plan
List record categories under a specified record series or file plan
List record folders under a record category
Get a file plan that matches a specified name
Get a record series that matches a specified name under a specified file plan
Get a record category that matches a specified name under a specified file plan or record series
Get a record folder that matches a specified name under a specified record category
Add a record category attribute
Modify a record category attribute
Return direct children of a record management object
Make a record
Update a record
Get a recordized object given a record id
Unrecordize a record from a given record category or record folder
Set record configuration for a folder
Delete record configuration for a folder
Get a required record category for a specified folder
The RecordsManager uses the following items:
File Plan: Document containing the disposition authority of a set of Records. A File Plan may contain Record Series and Record Categories.
Record Series: Named container for a set of Record Categories.
Record Category: Description of a set of Records within a File Plan. Each Record Category has retention and disposition data associated with it that is applied to all Record Folders and Records within it.
Record Folder: Extension of a Record Category used to aggregate Records by cut-off date.
Record: Information, regardless of medium, controlled by a particular Record Category.
The PagingManager allows control over pagination of items. When dealing with large item arrays (such as the result of a search), certain clients may find it is more convenient to deal with just a single "page" of items at a time. This approach is often favored by users who have low network bandwidth.
The PagingManager supports the following operations:
Store a list of items in a paging list
Retrieve a page of items of a specified size from the paging list at a specified start index
Note that there is only one paging list item array per session.
The CategoryManager provides functions for configuring categories. Publicly accessible repository objects such as Document and Folder can store traditional file system metadata such as description, create_date, created_by, last_modified_date, and last_modified_by. Custom file system metadata is represented in Oracle Content Services by category objects.
Attributes hold the data that describes items in Oracle Content Services. Categories contain and organize attributes, as well as contain other categories, or category subclasses. When a specified category is applied to a document, for example, that document will contain the attributes of that category, as well as the attributes of the parent, or superclass, category.
A category configuration may be applied to a folder. This specifies which categories are required and allowed for items in that folder. It also specifies whether or not subfolders may override the configuration, and whether or not versioning is enabled.
For example, consider a root category called Project Category. This category contains an attribute called Project Number and another category called Project Document Category. This category subclass contains three attributes called Billable Material, Document Type, and Document Reviewer. For each attribute, you can define its type, whether or not it is required, a default value, and whether or not its default value can be overridden. For example, Billable Material can be a boolean value whose value is required, its default value "true", and whose default value can be overridden.
If an instance of Project Document Category is applied to an item, that item will have the attributes of Project Document Category as well as the attributes from Project Category.
The CategoryManager supports the following operations:
Create, update, and delete categories and instances of categories
Retrieve a list of all categories, or category subclasses of a specified category
Retrieve, add, modify, and remove attributes from a category.
Retrieve, apply, modify, and remove a category configuration for a specified folder
These managers handle users and groups.
The UserManager supports the following operations:
Get a user with a specified name
Get and set user preferences for the current user with the specified preference keys
Get and set domain-level (site-level) default user preference values
Find provisioned users in the domain matching the specified search criteria
Find users in the current user's Oracle Internet Directory (OID) that match the specified search criteria
Synchronize the preferences of the current or specified user with those found in Oracle Internet Directory
Search for a list of provisioned users in the current domain
Search for a specific user by name
The GroupManager allows configuration of groups. A group is a collection of users and groups that can be managed as a single unit. Groups allow you to conveniently and quickly assign privileges to a collection of users without having to assign them to each user individually. Oracle Content Services groups are locally managed application objects and distinct to OID groups, which are not directly supported in this release. You can, however, manually provision OID groups as Oracle Content Services groups by using the GroupManager Web service.
Two distinct lists are maintained within a Oracle Content Services group: the member list, and the manager list. Managers may add and remove members and other managers from the group, and rename or delete the group.
The GroupManager supports the following operations:
Search for, create, update, and delete groups
Add and remove members and managers from a group
The SecurityManager allows granting and revoking of roles to users and groups. A role is a set of access permissions that provide a user or a group privileges to perform certain operations. Chapter A, "Oracle Content Services Roles" provides the list of roles and their explicit permissions that ship out-of-the-box (OOTB) with Oracle Content Services. Two types of roles exist: core administration roles and standard (non-administration) roles. Some roles can be granted at a domain level, while other roles can be granted at the container or workspace level.
The SecurityManager supports the following operations:
Retrieve, delete, create, and update roles
Retrieve the available roles in the domain that apply to a specified item or item type
Update, add grants to, or remove an item's security configuration. A security configuration is the set of all roles granted on a specific item (such as a workspace).
Retrieve the set of users that are granted a specified role on a specified security configuration.
Check whether or not the specified user or group has a specified permission or a specified role on a specified target item
These managers help organize items in Oracle Content Services.
The WorkspaceManager allows creation and configuration of workspaces, which are special folders created in a Container folder to store content such as documents and regular folders. Workspaces differ from containers and regular folders; they have a trash folder and can have an associated quota. Two types of workspaces are available: personal workspaces and shared workspaces. Personal workspaces are a special type of workspace for exclusive use by a user. Shared workspaces can be used by any user who is granted the appropriate privileges.
Workspaces must be uniquely named only within their parent container, while workspaces in different containers may have the same name. Therefore, the correct way to look up a workspace is by its path or unique ID.
The WorkspaceManager supports the following operations:
Create or delete a workspace
Update a workspace's name, description, or joinable flag
List joinable workspaces
Request to join a specified workspace
The ContainerManager allows creation and configuration of containers, which are special folders in the system from which workspaces (and sub-containers) can be created. Containers cannot contain documents, only other containers and workspaces. They have no quota and no trash. Containers can be created either directly under the domain, or under a parent container object.
The ContainerManager supports creating, deleting, and updating containers.
The WorkflowManager allows configuration of workflows. For a given item (such as an instance of a document or folder), a number of operations appropriate for the item's type can be configured to be controlled by the workflow. The list of available operations that can potentially be workflow controlled includes: createDocument, checkin, copy, delete, move, createWorkspace, joinWorkspace, and increaseQuota.
A workflow configuration is used to associate a particular item instance and operation type with a workflow item. A workflow configuration can be set to triggered (non-blocking) or approval-based (blocking). A triggered configuration means that the registered operation will occur right away (as if it were not workflow-driven), but a workflow process will still be started. An approval-based configuration means that the registered operation will not occur until the workflow process is approved.
An example of using a triggered workflow could be to capture all createDocument (upload) requests on a folder item and use logic in the workflow to respond to this event, such as calling a Web service, or logging the createDocument request to a file. An example of using an approval-based workflow could be to capture all delete requests and require that a particular responder approve the deletion of the particular item(s).
The WorkflowManager supports the following operations:
return all registered workflow instances
set a workflow configuration on a given item for the given operation type
remove a workflow configuration from a given item for the given operation type
retrieve all workflow configurations that exist for the given item
retrieve workflow configuration for the given item that matches the given operation type
validate that value of given workflow parameter is valid for the given workflow
The DomainManager allows configuration of Oracle Content Services domains. Every instance may have one or more domains (or sites). Each domain is an organizational entity that contains users and their content, metadata, and business rules.
The DomainManager supports obtaining the default domain and updating settings for a specified domain.
The QuotaManager limits the amount of content that can reside in a Workspace (including users' personal workspaces).
The QuotaManager supports the following operations:
Update the amount of allocated quota for a specified item
Request an update to allocated quota for a specified item
Calculate consumed quota for a specified item
These managers handle connections between clients and Oracle Content Services.
The RemoteLoginManager provides session creation and logout capabilities.
The RemoteLoginManager supports authenticating a user based on username and password, and disconnecting the current user session.
The SessionManager manages session information when performing transactions. When a client performs an operation in Oracle Content Services using Web services, such as creating, modifying, or deleting an object, the changes are immediately committed to the repository. However, in some cases the client may need to commit a set of dependent operations together; the client may need to ensure that if all these dependent operations cannot be successfully performed, none of these operations will not be performed. In other words, these operations must be atomically committed or rolled back. SessionManager provides methods that enable clients to wrap operations in a transaction block that can be used to control when the changes are committed to the repository.
The SessionManager supports the following operations:
Return the current user connected as an item
Switch the current session in and out of administration mode
Begin, commit, or rollback a specified transaction during this session
Keep alive a session to prevent it from timing out
Get supplied session properties (such as LOGIN_USER, SESSION_TIMEOUT, TRANSACTION_TIMEOUT)
Oracle Oracle Content Services supports nested transactions. Consider the following example:
1 Begin Outer-Transaction2 Begin Inner-Transaction3 perform some operation4 Begin Inner-Transaction5 perform some operation6 Abort (Rollback) Inner-Transaction7 Commit Inner-Transaction8 Abort (Rollback) Outer-Transaction
The innermost transaction (lines 4-6) is rolled back. Hence, any changes made in that particular transaction will never be applied. The encapsulating inner transaction (lines 2-7) is set to be committed, though its changes may be rolled back by the outer transaction. Because the outer transaction (line 8) is rolled back, any changes set to be committed in the inner transactions will not be applied. Thus, inner transactions are essentially save-points. They can be rolled back individually, but in order for them to be committed, the outer transaction must be committed.
The RequestManager allows operations on an item (such as copy, move, delete, and check-in) to be configured for control by a workflow. For example, the FileManager.delete() operation will invoke a DeleteRequest if workflow is enabled on the instance, and the Delete operation is workflow-enabled for the item being deleted.
The RequestManager supports the following operations:
retrieve a list of requests submitted by the given user matching the given request criteria
retrieve a list of requests for which the given user is responder to matching the given request criteria
delete one or more requests with given IDs
approve request with given ID for the given user
deny request with the given ID for the given user
cancel request with the given ID for the given user
acknowledge request with the given ID for the given user
invoke a "UserRequest" for the given set of target items. If the target item is controlled by a UserRequestWorkflowConfiguration, the associated custom workflow will be activated.
return whether the given operation/action is workflow-enabled (i.e. request based) for the given item
The ServiceToServiceManager uses the Service to Service (S2S) authentication framework to allow a trusted partner application to establish user sessions with a trusting provider application on behalf of its users, without having to supply any credentials for the users. The partner application instead supplies with each user session login request a digest credential (or potentially basic credential over HTTPS) that is used to authenticate the partner as being trusted to the provider service.
|
Note: The AXIS Java client stubs shipped with Oracle Content Services do not support digest authentication (see http://ws.apache.org/axis/java/security.html). Clients that use the Java stubs can authenticate through basic authentication, or by using an HTTP client and the S2S servlet. |
Oracle Content Services 10g operates as the trusting provider service, with the partner service being potentially any application (registered/configured with OID) that is capable of establishing a client SOAP over HTTP Web Service connection with digest authentication headers. For this manager to function, the server must be configured for S2S authentication and the instance property IFS.DOMAIN.CREDENTIALMANAGER.ServiceToServiceAuthenticationEnabled set to true.
The ServiceToServiceManager provides the ability to:
Authenticate a user with given username. The S2S header ORA_S2S_PROXY_USER must also be set to a non-null value corresponding to a valid OID user (it can be any user, such as orcladmin)
As an example, consider a custom portlet within Oracle Portal that displays a user's most recently accessed documents in Oracle Content Services. The sequence of operations would be similar to the following:
User "matt" authenticates to Oracle Portal (through the Oracle Login Server)
A default portal user home page containing the "most recent documents" portlet is requested to be displayed.
The portlet checks to see if an existing Oracle Content Services session cookie exists for the user in the user's HttpSession (or equivalent) object store. If no existing session exists, proceed with service to service authentication (step 4). Otherwise, obtain a FileManager (step 7) and make the appropriate call to retrieve the documents.
The portlet obtains the portal service's credentials from a credential store (such as Oracle Internet Directory).
The portlet initiates a Web Service request to the Oracle Content Services ServiceToServiceLoginManager with digest authentication HTTP headers present that identify the partner service (Oracle Portal), and HTTP header ORA_S2S_PROXY_USER set to a non-null value (for example, "matt"). The ServiceToServiceLoginManager login method is called, supplying the user name of the portal authenticated user ("matt" [@non-default realm]).
A session cookie is returned that identifies the newly created Oracle Content Services user session, which is then stored in an appropriate location, such as the user's HttpSession object.
Using the session cookie, obtain a FileManager, and then call the getMostRecentDocuments() method.
Process the returned item array and render portlet results.
