| Oracle® Content Services Application Developer's Guide 10g Release 1 (10.1.1) Part Number B14494-01 |
|
|
View PDF |
| Oracle® Content Services Application Developer's Guide 10g Release 1 (10.1.1) Part Number B14494-01 |
|
|
View PDF |
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 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 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 represent and handle files and folders.
Provides core document, folder, and link management capabilities. It supports the following operations:
Create documents, document definitions, folders and links
Copy, move, and delete items
Update documents, folders, and links
List items in a folder
List a user's most recently accessed documents
Uncompress items, and see if an item can be compressed
See if an item exists
See if an item can be created in a folder
See if a folder contains any links
Resolve path names
Get file conflict resolution options (such as overwrite or create new version) for a specific operation
Get a list of supported languages or character sets
Note:
Content upload/download is handled by standard HTTP PUT/GET, not Web service attachments.All workspaces (including personal workspaces) come with a trash folder that, if enabled, stores deleted items.
This manager 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).
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. This manager supports the following operations:
Empty an archive
Restore an item from the archive, and 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.
Sets user's default sort preferences for the following tables used by the Content Services application. These tables are defined in the FdkConstants class in the Web services Java API.
Checked out files
File listing
Group member list
Group members
Joinable workspaces
Locked files
Member listing
Recent files
Roles
Security config
Selected users or groups
User search results
Users or groups results
Version history
Virus names
Workflow report
In addition, many Web services operations that return item arrays support setting the sort sequence as part of their operation parameters.
This manager 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)
A search requires 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 7-1 Operators Supported by SearchExpression
| Operator | Syntax | Notes and Examples |
|---|---|---|
|
EQUAL |
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. Examples: SIZE GREATER_THAN 1048576NAME EQUAL *.doc |
|
GREATER_THAN |
||
|
GREATER_THAN_EQUAL |
||
|
LESS_THAN |
||
|
LESS_THAN_EQUAL |
||
|
NOT_EQUAL |
||
|
IN |
|
|
|
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 <NULL> CONTAINS "Content Services" |
|
AND |
Left and Right operands must themselves be SearchExpressions |
(SIZE GREATER_THAN 1048576) AND (NAME EQUAL *.doc) |
|
OR |
||
|
NOT |
Left operand must be null, Right operand must be a SearchExpression |
<NULL> NOT (((SIZE GREATER_THAN 1048576) AND (NAME EQUAL *.doc)) |
A Search is invoked by supplying SearchManager's search operation with a SearchExpression tree along with zero or more optional search options.
This manager 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
Locks prevent outside changes 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. This manager 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 DAV lock.
Track 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, 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
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 check 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.
This manager 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 the versions of an item
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
Scans and potentially repairs documents for viruses. 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 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 receive 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.
This manager 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
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 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 dispositions 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. Record Folders may be used to break Records into periods supporting different retention and disposition than the containing Record Category.
Record: Information, regardless of medium, controlled by a particular Record Category.
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 end-users who do have low network bandwidth.
This manager 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.
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 Content Services by category objects.
Attributes hold the data that describes items in Content Services. Categories contain and ogranize 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 subfolders may override the configuration, and wheter versioning is enabled.
For example, a root category called Project Category can be created. 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 it is required, a default value, and whether 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.
This manager supports the following operations:
Create, update and delete categories and instances of categories
Retrieve a list of all categories, or category suclasses 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.
This manager supports the following operations:
Search for a list of users from the current credential manager
Search for a list of provisioned users in the current domain
Search for a specific user by name
Specify or retrieve user preferences for a specified user
Specify or redeive domain level default user preference
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. Content Services groups are locally managed application objects and distinct to Oracle Internet Directory (OID) groups, which are not directly supported in this release. You can, however, manually provision OID groups as Content Services groups by using the GroupManager Web service.
Two distinct lists are maintained within a 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.
This manager supports the following operations:
Search for, create, update, and delete groups
Add and remove members and managers from a group
Grants and revokes roles to users or 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 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.
This manager 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 the specified user or group has a specified permission or a specified role on a specified target item
These managers help organize items in Content Services.
Workspaces are special folders that can be created in a Container folder to store content including documents and regular folders. Workspaces differ from containers and regular folders: they have a trash folder and can have quota associated with them. 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; workspaces in different containers may have the same name. Therefore, the correct way to look up a workspace is its path or unique ID.
This manager 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
Containers are special folders in the system from which workspaces (and sub-containers) can be created. Containers can be created either directly under the domain, or under a parent container object. This manager supports creating, deleting, and updating containers.
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 using logic in the workflow respond to this event, such as calling a web service, or logging the createDocument request to a file etc. 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).
This manager provides the ability to:
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 exists 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
A Content Services 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. This manager supports obtaining the default domain and updating settings for a specified domain.
Limits the amount of content that can reside in a Workspace (including users' personal workspaces). This manager supports the follwing 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 Content Services.
Provides session creation and logout capabilities. This manager supports authenticating a user based on username and password and disconnecting the current user session.
When a client performs an operation in 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.
This manager supports the following operations:
Return the current user connected as an item
Switch the current session into one of the administration modes (currently only one administration mode is available called DOMAIN) or out of administration mode (called NORMAL)
Begin, commit, or rollback a specified transaction during this session
Keep alive a session to prevent it from timing out
Certain operations on an item (such as copy, move, delete, checkin, and so on) can be configured so as to be controlled by a workflow. For example, the FileManager.delete() operation will invoke a DeleteRequest should workflow be enabled on the instance, and the 'Delete' operation be workflow enabled for the particular item being deleted. This manager provides the ability to:
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 Service to Service (S2S) authentication framework allows 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.
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.
This manager 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)
