Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Business Rules Java API Reference 10g Release 3 (10.1.3) B19040-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 (details pending) 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.Principal`argument 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 `DocumentID`s.
`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 `DocumentID`s.
  Parameters:
    `marker` - the marker.
    `ids` - an array of `DocumentID`s 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 `DocumentID`s in the array are invalid

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Business Rules Java API Reference 10g Release 3 (10.1.3) B19040-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2006, Oracle. All rights reserved.