Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.ifs.common
Class RandomAccessor

All Known Implementing Classes:
  S_RandomAccessorImpl

    public interface class RandomAccessor

RandomAccessor provides random read/write access to a document's content.

A RandomAccessor instance is associated with a particular document. The `RandomAccessor.read(long, byte[], int, int)` method allows random access to the document's content, using the ContentObject referenced by the document when the RandomAccessor was created. The content size can be obtained by calling `RandomAccessor.length()`.

If a RandomAccessor `is writeable`, the document's content can be updated by calling `RandomAccessor.write(long, byte[], int, int)` and `RandomAccessor.truncate(long)`. As changes are made by `write` and `truncate`, they are visible to `read` and `length`. However, the changes are not visible outside of the RandomAccessor until `RandomAccessor.close()` is called. Upon `close`, a new ContentObject is created and the document's CONTENTOBJECT attribute is set to reference that new ContentObject. If, prior to `close`, `LibrarySession.beginTransaction()` was called to start an explicit transaction, these changes occur within that transaction and will not be visible to other sessions until that transaction completes. If the transaction is instead aborted, the changes are discarded. The changes are also discarded if `RandomAccessor.dispose()` is called instead of `close`.

Prior to `close`, the RandomAccessor may be used in successive transactions in a session. However, the effect of aborting a transaction in which `write` or `truncate` was called is unspecified, unless `close` was also called in the same transaction, in which case the changes are discarded. This is because some Medias are non-transactional.

In general, successive reads and writes against a RandomAccessor will be more performant if they are performed in a single transaction created by calling `LibrarySession.beginTransaction()`. This is because RandomAccessor needs to re-establish some of its internal state when the in-progress transaction changes.

A RandomAccessor is initially bound to the session in which it was created. The `RandomAccessor.setSession(LibrarySessionInterface)` method may be called to bind the RandomAccessor to a different session. This capability must be used carefully. Once either `write` or `truncate` have been invoked on a RandomAccessor, `setSession` will throw an exception if the RandomAccessor has been used within a transaction that has yet to complete or abort.

When a writeable RandomAccessor is created, an expiration period can be specified. If no expiration period is specified, the expiration period defaults to the `domain property` named `IFS.DOMAIN.RANDOMACCESSOR.ExpirationPeriod`. If a time interval equal to the expiration period passes in which neither `write` nor `truncate` is called, the RandomAccessor will expire as if `dispose` had been called. Expiration is performed periodically in the background. Once a RandomAccessor expires, further operations on it will throw an exception. A writeable RandomAccessor will not expire if its content has not been changed (that is, if neither `write` nor `truncate` has been called). A writeable RandomAccessor will also not expire if it has been used within a transaction that has yet to complete or abort. Non-writeable RandomAccessors never expire.

(Published)

Method Summary
`void` | `close()` Closes this RandomAccessor, saving any changes to the document.
`void` | `dispose()` Disposes this RandomAccessor, discarding any changes to the document.
`java.lang.Long` | `getContentObjectId()` Gets the id of the ContentObject being accessed by this RandomAccessor.
`java.lang.Long` | `getDocumentId()` Gets the id of the Document being accessed by this RandomAccessor.
`LibrarySessionInterface` | `getSession()` Gets the session associated with this RandomAccessor.
`boolean` | `isWriteable()` Gets whether this RandomAccessor is writeable.
`long` | `length()` Gets the content length.
`int` | `read(long pos, byte[] b, int off, int len)` Reads bytes from content into a byte array.
`void` | `setSession(LibrarySessionInterface session)` Sets the session associated with this RandomAccessor.
`void` | `truncate(long len)` Truncates the content to exactly `len` bytes in length.
`void` | `write(long pos, byte[] b, int off, int len)` Writes bytes from a byte array.

Method Detail

### getDocumentId

    java.lang.Long getDocumentId()
                                 throws IfsException

  Description copied from interface: `RandomAccessor`
  Gets the id of the Document being accessed by this RandomAccessor.

  Returns:
    the Document id
  Throws:
    `IfsException` - if the operation fails
  (Published)

### getContentObjectId

    java.lang.Long getContentObjectId()
                                      throws IfsException

  Description copied from interface: `RandomAccessor`
  Gets the id of the ContentObject being accessed by this RandomAccessor.

  Returns:
    the ContentObject id
  Throws:
    `IfsException` - if the operation fails
  (Published)

### setSession

    void setSession(LibrarySessionInterface session)
                    throws IfsException

  Description copied from interface: `RandomAccessor`
  Sets the session associated with this RandomAccessor.

  A RandomAccessor is initially bound to the session in which it was created. Call this method to safely use the RandomAccessor in the context of a different session.

  Parameters:
    `session` - the session
  Throws:
    `IfsException` - if the operation fails
  (Published)

### getSession

    LibrarySessionInterface getSession()
                                       throws IfsException

  Description copied from interface: `RandomAccessor`
  Gets the session associated with this RandomAccessor.

  Returns:
    the session
  Throws:
    `IfsException` - if the operation fails
  (Published)

### read

    int read(long pos,
             byte[] b,
             int off,
             int len)
             throws IfsException

  Description copied from interface: `RandomAccessor`
  Reads bytes from content into a byte array.

  Reads from position `pos` in content, where 0 is the first byte in content, 1 is the second byte, and so forth.

  Attempts to read as many as `len` bytes, but a smaller number of bytes may actually be read. Returns 0 if `len` is 0. Otherwise, blocks until at least one byte is read, the end of file is detected, or an error occurs. Returns the number of bytes actually read.

  The bytes are read into `b` starting at index `off`. If `r` is the number of bytes actually read (as returned by the method), the bytes are read into elements `b[off]` through `b[off+r-1]`. Elements `b[off+r]` through `b[off+len-1]` are not changed. Additionally, elements `b[0]` through `b[off-1]` are never changed. Similarly, `b[off+len]` through `b[b.length-1]` are never changed.

  An exception is thrown upon any of the following conditions:

  - `pos < 0`
  - `pos >= length()`
  - `b == null`
  - `off < 0`
  - `len < 0`
  - `off + len > b.length`

  Parameters:
    `pos` - the position in content from which to read
    `b` - the buffer into which to read
    `off` - the offset in the buffer
    `len` - the maximum number of bytes to read
  Returns:
    the actual number of bytes read
  Throws:
    `IfsException` - if the operation fails
  (Published)

### isWriteable

    boolean isWriteable()
                        throws IfsException

  Description copied from interface: `RandomAccessor`
  Gets whether this RandomAccessor is writeable.

  Returns:
    whether writeable
  Throws:
    `IfsException` - if the operation fails
  (Published)

### write

    void write(long pos,
               byte[] b,
               int off,
               int len)
               throws IfsException

  Description copied from interface: `RandomAccessor`
  Writes bytes from a byte array.

  If `len` is 0, the content is unchanged. Otherwise, the content is changed as specified in the following two paragraphs.

  The bytes `b[off]` through `b[off+len-1]` are written to positions `pos` through `pos + len - 1` in the content, where 0 is the position of the first byte in content, 1 is the second byte, and so forth.

  If, prior to the call, `pos + len > length()`, the method will extend the content so that `pos + len == length()`.

  An exception is thrown upon any of the following conditions:

  - `pos < 0`
  - `b == null`
  - `off < 0`
  - `len < 0`
  - `off + len > b.length`
  - this RandomAccessor is not writeable

  Parameters:
    `pos` - the position in content from which to write
    `b` - the buffer from which to write
    `off` - the offset in the buffer
    `len` - the number of bytes to write
  Throws:
    `IfsException` - if the operation fails
  (Published)

### truncate

    void truncate(long len)
                  throws IfsException

  Description copied from interface: `RandomAccessor`
  Truncates the content to exactly `len` bytes in length.

  If `len > length()`, the content at byte positions `len` through `length() - 1` are dropped, where 0 is the position of the first byte in content, 1 the second byte, and so forth.

  If `len < length()`, the content is resized by zero-filling positions `length()` through `len - 1`.

  If `len == length()`, the method has no effect.

  In all three cases, after the method returns, `length()` will return `len`.

  An exception is thrown if `len < 0` or this RandomAccessor is not writeable.

  Parameters:
    `len` - the desired content length
  Throws:
    `IfsException` - if the operation fails
  (Published)

### length

    long length()
                throws IfsException

  Description copied from interface: `RandomAccessor`
  Gets the content length.

  Returns:
    the length, in bytes
  Throws:
    `IfsException` - if the operation fails
  (Published)

### dispose

    void dispose()
                 throws IfsException

  Description copied from interface: `RandomAccessor`
  Disposes this RandomAccessor, discarding any changes to the document.

  To release resources held by the RandomAccessor, an application should call either `close` (to save changes) or `dispose` (to discard changes).

  Throws:
    `IfsException` - if the operation fails
  (Published)

### close

    void close()
               throws IfsException

  Description copied from interface: `RandomAccessor`
  Closes this RandomAccessor, saving any changes to the document.

  For a writeable RandomAccessor, a new ContentObject is created for the updated content, and the document's CONTENTOBJECT attribute is set to reference this new ContentObject. Any other changes specified by the DocumentDefinition supplied in creating this RandomAccessor are also applied.

  For a non-writeable RandomAccessor, `close` is equivalent to `dispose`.

  To release resources held by the RandomAccessor, an application should call either `close` (to save changes) or `dispose` (to discard changes).

  Throws:
    `IfsException` - if the operation fails
  (Published)

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD