RandomAccessor (ecmsdk-api 3.4.0 API)

All Known Implementing Classes:

S_RandomAccessorImpl
```
public interface RandomAccessor
```
RandomAccessor provides random read/write access to a document's content.
A RandomAccessor instance is associated with a particular document. The 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 length().
If a RandomAccessor is writeable, the document's content can be updated by calling write(long, byte[], int, int) and 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 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 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 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

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`close()` Closes this RandomAccessor, saving any changes to the document.
`void`	`dispose()` Disposes this RandomAccessor, discarding any changes to the document.
`Long`	`getContentObjectId()` Gets the id of the ContentObject being accessed by this RandomAccessor.
`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
```
Long getDocumentId()
            throws IfsException
```
    Gets the id of the Document being accessed by this RandomAccessor.
    
    Returns:
    
    the Document id
    
    Throws:
    
    IfsException - if the operation fails
    
    (Published)
  - getContentObjectId
```
Long getContentObjectId()
                 throws IfsException
```
    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
```
    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
```
    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
```
    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
```
    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
```
    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
```
    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
```
    Gets the content length.
    
    Returns:
    
    the length, in bytes
    
    Throws:
    
    IfsException - if the operation fails
    
    (Published)
  - dispose
```
void dispose()
      throws IfsException
```
    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
```
    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)

Interface RandomAccessor

Method Summary

Method Detail

getDocumentId

getContentObjectId

setSession

getSession

read

isWriteable

write

truncate

length

dispose

close