Skip navigation links

oracle.rules.sdk.store
Interface RepositoryConnection

All Known Implementing Classes:

AbstractRepositoryConnection

public interface RepositoryConnection

The repository connection interface for the Oracle Business Rules Rules SDK. This interface contains the basic functionality that the Rules SDK requires from a repository and is used to store and retrieve rule documents created with the Oracle Business Rules Rules SDK.

Rule Documents

Rule documents are XML documents. The document content should be considered opaque. Rule documents may contain character data from locales that differ from the default for the underlying repository. This character data must be preserved. Thus, if the documents are stored as XML text, they should be stored in UTF-8 to avoid unwanted character set conversions. An XML helper class contains some convenience methods for XML processing.

Rule documents are stored and retreived using instances of the DocumentID class.

Rule Document Markers

A DocumentID contains a marker which is a Unicode identifier. The markDocuments method associates a new marker with the specified documents. Marking a document should result in a new copy of the original document which is identified by a DocumentID that only differs from the original DocumentID in that it contains the new marker. The new document should have a creation timestamp (if supported) and a last modification timestamp that reflect the time at which the document was marked. A marked document may be marked again with a different marker. Marking documents may be done incrementally. That is, at different points in time, markDocuments may be invoked with the same marker. However, an attempt to mark a document that has already been marked with the same marker is an error.

Repository Connection Initialization

The init method is invoked when a new repository connection is instantiated by the getRepositoryConnection method in the RepositoryConnectionFactory. Any repository specific information necessary for initializing the repository connection should be passed in the properties argument. The details of the information required and the corresponding keys should be documented.

Security

The java.security.Principalargument represents the identity which was authenticated in the context of the Rule SDK client. If no user was authenticated this should be null. In a J2EE servlet or EJB, the authenticated user is available from either HttpServletRequest or EJBContext. RepositoryConnection implementations should avoid using the role information.

If the underlying repository supports or requires authenticatation, this identity can be used to map to credentials to be used in for authentication with the repository. The definition, initialization, and access mechanism for this mapping is the responsibility of each implementation of this interface.

Document Metadata

The getDocumentMetadata method returns metadata about a specific document. The metadata should include the following items.

Metadata	Value Type
The time that the document was last modified.	java.util.Date
The time that the document was created (if available).	java.util.Date
The document revision (if revision control is supported).	java.util.String
The tags tags associated with this revision of the document (if tags are supported).	java.util.String[]

Implementation specific document metadata may also be included. The meaning of this metadata as well as the keys used to store it should be documented.

Field Summary

static java.lang.String	CREATION_METADATA The key for the document creation date (java.util.Date) in the Map of metadata returned by getDocumentMetadata.
static java.lang.String	LAST_MODIFIED_METADATA The key for the last modification date (java.util.Date) in the Map of metadata returned by getDocumentMetadata.
static java.lang.String	REVISION_CONTROL_OPTION Option for indicating that the underlying repository supports document revision control.
static java.lang.String	REVISION_METADATA The key for the document revision string in the Map of metadata returned by getDocumentMetadata.
static java.lang.String	TAG_METADATA The key for the string array (String[]) of tags in the Map of metadata returned by getDocumentMetadata.
static java.lang.String	TAGS_OPTION Option for indicating that the underlying repository supports tags.

Method Summary

boolean	cachesModifications() Returns true if the underlying implementation caches repository modifications.
void	createDocument(DocumentID id, org.w3c.dom.Document document) Creates a new document in the repository, identified by the specified Document with the specified initial content.
DocumentID	createDocumentID() Creates an empty DocumentID for use with this RepositoryConnection.
DocumentID	createDocumentID(DocumentID id) Creates a DocumentID for use with this RepositoryConnection from the specified DocumentID.
DocumentID	createDocumentID(java.lang.String dictionaryName, java.lang.String documentType, java.lang.String documentName, java.lang.String marker, java.lang.String revision, java.lang.String tag) Creates a DocumentID for use with this RepositoryConnection from the individual components.
void	deleteDocument(DocumentID id) Deletes the document identified by the specified DocumentID from the repository.
void	flush() Flushes repository modifications to the underlying repository.
org.w3c.dom.Document	getDocument(DocumentID id) Gets the document identified by the specified DocumentID.
java.util.Map	getDocumentMetadata(DocumentID id) Gets the metadata for the document identified by the specified DocumentID.
void	init(java.security.Principal principal, java.util.Locale locale, SensitiveDataCallback callback, java.util.Properties properties) Initializes a repository connection.
boolean	isOptionSupported(java.lang.String option) Tests if the specified option is supported.
DocumentID[]	listDocuments(DocumentID id) Returns a list of DocumentID's that match the specified DocumentID.
void	markDocuments(java.lang.String marker, DocumentID[] ids) Associates the marker with the documents identified by the array of DocumentIDs.
void	release() Releases this repository connection.
void	updateDocument(DocumentID id, org.w3c.dom.Document document) Updates a document identified by the specified DocumentID with the specified content.

Field Detail

REVISION_CONTROL_OPTION

public static final java.lang.String REVISION_CONTROL_OPTION

Option for indicating that the underlying repository supports document revision control.

See Also:

Constant Field Values

TAGS_OPTION

public static final java.lang.String TAGS_OPTION

Option for indicating that the underlying repository supports tags.

See Also:

Constant Field Values

CREATION_METADATA

public static final java.lang.String CREATION_METADATA

The key for the document creation date (java.util.Date) in the Map of metadata returned by getDocumentMetadata.

See Also:

Constant Field Values

LAST_MODIFIED_METADATA

public static final java.lang.String LAST_MODIFIED_METADATA

The key for the last modification date (java.util.Date) in the Map of metadata returned by getDocumentMetadata.

See Also:

Constant Field Values

REVISION_METADATA

public static final java.lang.String REVISION_METADATA

The key for the document revision string in the Map of metadata returned by getDocumentMetadata.

See Also:

Constant Field Values

TAG_METADATA

public static final java.lang.String TAG_METADATA

The key for the string array (String[]) of tags in the Map of metadata returned by getDocumentMetadata.

See Also:

Constant Field Values

Method Detail

init

public void init(java.security.Principal principal,
                 java.util.Locale locale,
                 SensitiveDataCallback callback,
                 java.util.Properties properties)
          throws StoreException

Initializes a repository connection. This method is invoked by the RepositoryConnectionFactory after the implementation class has been instantiated.

Parameters:

principal - the identity to be used for authorization purposes.

locale - the Locale to be used. May be null.

callback - the callback object for retrieving sensitive data

properties - initialization parameters required by a specific implementation of this interface.

Throws:

StoreException - if an error was encountered initializing this session.

release

public void release()
             throws StoreException

Releases this repository connection. Any resources utilized by this connection that can be released should be. If there is any state associated with the repository connection that must be persistent between connection, it is the responsibility of the implementation to save that state. After a connection is released, invoking any other methods on this interface is not allowed and behavior is undefined.

Throws:

StoreException - if an error was encountered releasing this session.

cachesModifications

public boolean cachesModifications()

Returns true if the underlying implementation caches repository modifications. flush must be invoked to flush the modifications to the repository.

Returns:

true if repository modifications are cached.

flush

public void flush()
           throws StoreException

Flushes repository modifications to the underlying repository. If cachesModifications returns false, the behavior of this method is undefined.

Throws:

StoreException - if an error was encountered flushing the modifications.

isOptionSupported

public boolean isOptionSupported(java.lang.String option)

Tests if the specified option is supported.

Parameters:

option - the name of the option.

Returns:

true if the specified option is supported.

createDocument

public void createDocument(DocumentID id,
                           org.w3c.dom.Document document)
                    throws DocumentException,
                           DocumentExistsException,
                           DocumentIDException,
                           StoreException

Creates a new document in the repository, identified by the specified Document with the specified initial content. The DocumentID must not specify a tag or a revision.

Parameters:

id - a DocumentID that identifies the document to be created. The ID should be validated prior to invoking this method.

document - the initial content of the document.

Throws:

DocumentException - if an error is encountered processing the document

DocumentExistsException - if a document corresponding to DocumentID already exists.

DocumentIDException - if the DocumentID is not valid

StoreException - if an error was encountered creating the document in the store.

deleteDocument

public void deleteDocument(DocumentID id)
                    throws DocumentNotFoundException,
                           DocumentIDException,
                           StoreException

Deletes the document identified by the specified DocumentID from the repository. The DocumentID must not specify a tag nor a revision.

Parameters:

id - a DocumentID that identifies the document to be deleted. The ID should be validated prior to invoking this method.

Throws:

DocumentNotFoundException - if a document corresponding to the specified DocumentID does not exist.

DocumentIDException - if the DocumentID is not valid

StoreException - if an error was encountered deleting the document.

getDocument

public org.w3c.dom.Document getDocument(DocumentID id)
                                 throws DocumentNotFoundException,
                                        DocumentIDException,
                                        StoreException

Gets the document identified by the specified DocumentID.

Parameters:

id - a DocumentID that identifies the document. The ID should be validated prior to invoking this method.

Returns:

a Document instance for the retrieved document

Throws:

DocumentNotFoundException - if a document corresponding to the specified DocumentID does not exist.

DocumentIDException - if the DocumentID is not valid

StoreException - if an error occurs retrieving the document.

updateDocument

public void updateDocument(DocumentID id,
                           org.w3c.dom.Document document)
                    throws DocumentNotFoundException,
                           DocumentIDException,
                           DocumentException,
                           StoreException

Updates a document identified by the specified DocumentID with the specified content. The DocumentID must not specify a tag nor a revision. The new document content overwrites the previous content.

Parameters:

id - a DocumentID that identifies the document. The ID should be validated prior to invoking this method.

document - the new content of the document.

Throws:

DocumentException - if an error is encountered processing the document

DocumentNotFoundException - if a document corresponding to the specified DocumentID does not exist.

DocumentIDException - if the DocumentID is not valid

StoreException - if document update fails

getDocumentMetadata

public java.util.Map getDocumentMetadata(DocumentID id)
                                  throws DocumentNotFoundException,
                                         DocumentIDException,
                                         StoreException

Gets the metadata for the document identified by the specified DocumentID.

Parameters:

id - a DocumentID that identifies the document. The ID should be validated prior to invoking this method.

Returns:

a Map containing the available metadata for the document

Throws:

DocumentNotFoundException - if a document corresponding to the specified DocumentID does not exist.

DocumentIDException - if the DocumentID is not valid

StoreException - if metadata retrieval fails for the document

listDocuments

public DocumentID[] listDocuments(DocumentID id)
                           throws DocumentIDException,
                                  StoreException

Returns a list of DocumentID's that match the specified DocumentID. The specified id may contain wildcards.

Parameters:

id - a DocumentID that may contain wildcards. The ID should be validated prior to invoking this method.

Returns:

a List of DocumentID's. The list is empty if no documents match.

Throws:

DocumentIDException - if the DocumentID is not valid

StoreException - if an error is encountered.

createDocumentID

public DocumentID createDocumentID()

Creates an empty DocumentID for use with this RepositoryConnection. Once created and populated, it must be validated for use by invoking the validation method appropriate for the intended use.

createDocumentID

public DocumentID createDocumentID(java.lang.String dictionaryName,
                                   java.lang.String documentType,
                                   java.lang.String documentName,
                                   java.lang.String marker,
                                   java.lang.String revision,
                                   java.lang.String tag)

Creates a DocumentID for use with this RepositoryConnection from the individual components. Once created, it must be validated for use by invoking the validation method appropriate for the intended use.

Parameters:

dictionaryName - the name of the dictionary

documentType - the type of document

documentName - the name of the document

marker - a marker associated with the document

revision - a document revision string. It may be null.

tag - a tag string. It may be null.

createDocumentID

public DocumentID createDocumentID(DocumentID id)

Creates a DocumentID for use with this RepositoryConnection from the specified DocumentID. Once created, it must be validated for use by invoking the validation method appropriate for the intended use.

Parameters:

id - the DocumentID the new ID is populated from.

markDocuments

public void markDocuments(java.lang.String marker,
                          DocumentID[] ids)
                   throws StoreException,
                          DocumentNotFoundException,
                          DocumentIDException

Associates the marker with the documents identified by the array of DocumentIDs.

Parameters:

marker - the marker.

ids - an array of DocumentIDs which identify the documents to be associated with the marker. Each DocumentID should be validated prior to invoking this method.

Throws:

StoreException - if an error was encountered marking the documents.

DocumentNotFoundException - if no document exists for any DocumentID in the array.

DocumentIDException - if any of the DocumentIDs in the array are invalid

Skip navigation links