org.outerj.daisy.repository
Interface Document


public interface Document

A document in the repository. This object actually always represents one particular variant (branch-language combination) of the document. There is no separate object representing a document itself as such, access to documents is always done through a certain variant of it (since access control is also determined based on the information that is part of the variant). Letting a document object represent both the document and document variant was also the most backwards-compatible way to introduce the variants feature.

Since one object is used to manipulate both the document and document variant, most methods include a mentioning of whether they apply to the document or the document variant.

A document can be created using Repository.createDocument(String, String) or retrieved using Repository.getDocument(long, boolean).


Method Summary
 void addLink(java.lang.String title, java.lang.String target)
          Adds an out-of-line link (at the end of the list).
 void addToCollection(DocumentCollection collection)
          Adds the document variant to a supplied Collection.
 boolean canReadLiveOnly()
          Returns true if the current user can only access live data of the document.
 void changeDocumentType(long documentTypeId)
          Changes the document type of this document.
 void changeDocumentType(java.lang.String documentTypeName)
          See changeDocumentType(long).
 void clearCollections()
          Removes the document variant from all the collections it belongs to.
 void clearCustomFields()
          Removes all custom fields.
 void clearLinks()
          Removes all out-of-line links.
 void deleteCustomField(java.lang.String name)
          Removes the specified custom field.
 void deleteField(long fieldTypeId)
          Removes the specified field.
 void deleteField(java.lang.String name)
          Removes the specified field.
 void deleteLink(int index)
          Removes an out-of-line link.
 void deletePart(long partTypeId)
          Removes a part, passes silently if there is no part in the document with the given id.
 void deletePart(java.lang.String name)
          Removes a part, passes silently if there is no part in the document with the given name.
 AvailableVariants getAvailableVariants()
          Returns the available variants for this document.
 long getBranchId()
           
 DocumentCollections getCollections()
          Returns the collections the document variant belongs to, null if the document variant belongs to no Collections.
 java.util.Date getCreated()
          Gets the time this document was created.
 java.lang.String getCustomField(java.lang.String name)
          Gets the value of the specified custom field, or null if there is no custom field with that name.
 java.util.Map getCustomFields()
          Returns a map containing the fields, with the field type name being the key.
 long getDocumentTypeId()
          Returns the id of the document type to which this document adheres.
 Field getField(long fieldTypeId)
          Same as getField(String) but using the field type id.
 Field getField(java.lang.String fieldTypeName)
          Gets a field by field type name.
 Fields getFields()
          Gets all fields in the document.
 Fields getFieldsInOrder()
          Gets all fields in the document, sorted in the same order as the fields are defined in the document type.
 long getId()
          Returns the id of this document.
 long getLanguageId()
           
 java.util.Date getLastModified()
          The time this document was last saved.
 long getLastModifier()
          Returns the user id of the last user who saved this document.
 Version getLastVersion()
          Returns the Version object for the last stored version, or null for unsaved documents.
 long getLastVersionId()
          Returns the id of the last stored version.
 Links getLinks()
          Removes all out-of-line links.
 Version getLiveVersion()
          Returns the live version of this document, or null if there is none.
 long getLiveVersionId()
          Returns the id of the live version, or -1 if there is none.
 LockInfo getLockInfo(boolean fresh)
          Returns information about the current lock on the document variant.
 java.lang.String getName()
          Gets the name of this document.
 VersionState getNewVersionState()
          See setNewVersionState(VersionState).
 long getOwner()
          Returns the user id of the owner of this document.
 Part getPart(long partTypeId)
          Gets a part.
 Part getPart(java.lang.String name)
          Gets a part.
 Parts getParts()
          Returns the parts contained in the document variant, in unspecified order.
 Parts getPartsInOrder()
           
 java.lang.String getSummary()
          Returns a summary text for the document variant.
 long getUpdateCount()
           
 long getVariantCreatedFromBranchId()
          If the variant currently loaded in this document object is created from an existing branch, this method will return the id of that branch, otherwise it will return -1.
 long getVariantCreatedFromLanguageId()
          Similar to getVariantCreatedFromBranchId().
 long getVariantCreatedFromVersionId()
          Similar to getVariantCreatedFromBranchId().
 VariantKey getVariantKey()
           
 java.util.Date getVariantLastModified()
          The time the document variant was last saved.
 long getVariantLastModifier()
          Returns the user id of the last user who saved this document variant.
 long getVariantUpdateCount()
           
 Version getVersion(long id)
          Returns the requested version.
 Versions getVersions()
          Returns all versions stored for this document.
 org.outerx.daisy.x10.DocumentDocument getXml()
           
 org.outerx.daisy.x10.DocumentDocument getXml(long versionId)
          Gets the XML of the document but include the data from the specified version, instead of the current data.
 org.outerx.daisy.x10.DocumentDocument getXmlWithoutVariant()
           
 org.outerx.daisy.x10.DocumentDocument getXmlWithoutVersionedData()
           
 boolean hasCustomField(java.lang.String name)
          Returns true if there is a custom field with the specified name.
 boolean hasField(long fieldTypeId)
          Checks if the document contains the field with the specified field type id.
 boolean hasField(java.lang.String fieldTypeName)
          Checks if the document contains the field with the specified field type name.
 boolean hasPart(long partTypeId)
          Checks if the document variant has the part for the specified part type.
 boolean hasPart(java.lang.String name)
          Checks if the document variant has the part for the specified part type.
 boolean inCollection(DocumentCollection collection)
          Checks if the document variant belongs to the specified collection.
 boolean inCollection(long collectionId)
          Checks if the document variant belongs to the specified collection.
 boolean isPrivate()
          Is this a private document or not.
 boolean isRetired()
          Is this document retired or not.
 boolean isVariantNew()
          Returns true if the variant represented by this document object has never been stored yet.
 boolean lock(long duration, LockType lockType)
          Takes a lock on the document variant.
 boolean releaseLock()
          Releases the lock on the document variant.
 void removeFromCollection(DocumentCollection collection)
          Removes the document variant from a collection
 void save()
          Saves a document.
 void save(boolean validate)
          Saves the document and document variant.
 void setCustomField(java.lang.String name, java.lang.String value)
          Sets a custom field.
 void setField(long fieldTypeId, java.lang.Object value)
          Same as setField(String, Object) but using the id of the field type.
 void setField(java.lang.String name, java.lang.Object value)
          Sets the value of a field.
 void setName(java.lang.String name)
          Sets the name of the document.
 void setNewVersionState(VersionState versionState)
          Sets the VersionState that should be used if a new version is created when saving the document.
 void setOwner(long userId)
          Change the owner of this document.
 void setPart(long partTypeId, java.lang.String mimeType, byte[] data)
          Sets a part.
 void setPart(long partTypeId, java.lang.String mimeType, PartDataSource partDataSource)
          Sets a part.
 void setPart(java.lang.String partTypeName, java.lang.String mimeType, byte[] data)
          Sets a part.
 void setPart(java.lang.String partTypeName, java.lang.String mimeType, PartDataSource partDataSource)
          Sets a part.
 void setPartFileName(long partTypeId, java.lang.String fileName)
          Update the file name of an already existing part.
 void setPartFileName(java.lang.String partTypeName, java.lang.String fileName)
          Update the file name of an already existing part.
 void setPartMimeType(long partTypeId, java.lang.String mimeType)
          Update the mime-type of an already existing part.
 void setPartMimeType(java.lang.String partTypeName, java.lang.String mimeType)
          Update the mime-type of an already existing part.
 void setPrivate(boolean _private)
          Sets the private flag for this document, see also isPrivate().
 void setRetired(boolean retired)
          Sets the retired flag for this document, see also isRetired().
 void validate()
          Validates that this document confirms to its document type.
 

Method Detail

getId

long getId()
Returns the id of this document. For newly created documents, this method returns -1 until save() is called.


getBranchId

long getBranchId()

getLanguageId

long getLanguageId()

getVariantKey

VariantKey getVariantKey()

isVariantNew

boolean isVariantNew()
Returns true if the variant represented by this document object has never been stored yet.


getAvailableVariants

AvailableVariants getAvailableVariants()
                                       throws RepositoryException
Returns the available variants for this document. If the document is new and unsaved, this returns an empty list. If the document variant in this document is new and unsaved, the returned list will not yet contain this new variant. Thus only variants persisted in the repository are returned. This method does the same as Repository.getAvailableVariants(long).

Throws:
RepositoryException

getDocumentTypeId

long getDocumentTypeId()
Returns the id of the document type to which this document adheres. Document types themselve are managed via the RepositorySchema.

The document type is a variant-level property.


changeDocumentType

void changeDocumentType(long documentTypeId)
                        throws RepositoryException
Changes the document type of this document.

Will throw an exception if the document type does not exist.

Changing the documenttype does not influence the content of the document, you have to assure yourself that you update/add/remove parts and fields so that the document conforms to the document type.

The document type is a variant-level property.

Throws:
RepositoryException

changeDocumentType

void changeDocumentType(java.lang.String documentTypeName)
                        throws RepositoryException
See changeDocumentType(long).

Throws:
RepositoryException

getName

java.lang.String getName()
Gets the name of this document.

The document name is a variant-level property.


setName

void setName(java.lang.String name)
Sets the name of the document. The document name is not required to be unique, and is versioned, ie changing the document name and then saving the document will create a new version.

The document name is a variant-level property.


getOwner

long getOwner()
Returns the user id of the owner of this document. The owner is the user that created the document, unless changed.

The owner is a document-level property.


setOwner

void setOwner(long userId)
Change the owner of this document. Only users acting in the Administrator role, or the current owner, can change the owner.

The owner is a document-level property.


isPrivate

boolean isPrivate()
Is this a private document or not. A private document is a document that can only be accessed by its owner, or users having (and acting) in the role of Administrator.

This is a document-level property.


setPrivate

void setPrivate(boolean _private)
Sets the private flag for this document, see also isPrivate(). New documents are not private by default.

This is a document-level property.


getCreated

java.util.Date getCreated()
Gets the time this document was created.

This is a document-level property.


isRetired

boolean isRetired()
Is this document retired or not. A retired document behaves very much likes a deleted document. Retired documents don't show up in query results (unless specifically requested).

This is a variant-level property.


setRetired

void setRetired(boolean retired)
Sets the retired flag for this document, see also isRetired().

This is a variant-level property.


getLastModified

java.util.Date getLastModified()
The time this document was last saved. Returns null for documents that have never been saved yet.

This is a document-level property. See also getVariantLastModified().


getLastModifier

long getLastModifier()
Returns the user id of the last user who saved this document. Returns -1 for documents that have never been saved yet.

This is a document-level property. See also getVariantLastModifier().


getVariantLastModified

java.util.Date getVariantLastModified()
The time the document variant was last saved. Returns null for document variants that have never been saved yet.

This is a variant-level property. See also getLastModified().


getVariantLastModifier

long getVariantLastModifier()
Returns the user id of the last user who saved this document variant. Returns -1 for document variants that have never been saved yet.

This is a variant-level property. See also getLastModifier().


getVersions

Versions getVersions()
                     throws RepositoryException
Returns all versions stored for this document.

In a typical implementation, the returned Version objects will only contain basic information about the version (like its id and creation time) which is needed to show a version list, but the actual version content (fields, parts, ...) will only be loaded when requested.

This is a variant-level method.

Throws:
RepositoryException

getVersion

Version getVersion(long id)
                   throws RepositoryException
Returns the requested version.

Note that in contrast with the getVersions() method, typical implementations will usually return a Version object containing all details about the version.

This is a variant-level method.

Throws:
RepositoryException

getLastVersionId

long getLastVersionId()
Returns the id of the last stored version. For new, unsaved documents this returns -1.

This is a variant-level property.


getLastVersion

Version getLastVersion()
                       throws RepositoryException
Returns the Version object for the last stored version, or null for unsaved documents.

This is a variant-level method.

Throws:
RepositoryException

getLiveVersion

Version getLiveVersion()
                       throws RepositoryException
Returns the live version of this document, or null if there is none. The live version is the most recent version that has the state 'publish'.

This is a variant-level method.

Throws:
RepositoryException

getLiveVersionId

long getLiveVersionId()
Returns the id of the live version, or -1 if there is none.

This is a variant-level method.


canReadLiveOnly

boolean canReadLiveOnly()
Returns true if the current user can only access live data of the document.


setField

void setField(java.lang.String name,
              java.lang.Object value)
              throws DocumentTypeInconsistencyException
Sets the value of a field. The field must be part of the document type of this document.

This is a variant-level method.

Parameters:
name - name of the field type of the field to set.
value - the value of the field, the type of the object must be in correspondence with the ValueType of the field type. For multi-value fields, the value should be an array (i.e. Object[] or a more specifically typed array). For link field types, the value is a VariantKey object. The branch and language fields of the VariantKey object can be -1 to indicate they are the same as the containing document (recommended for most uses).
Throws:
DocumentTypeInconsistencyException

setField

void setField(long fieldTypeId,
              java.lang.Object value)
              throws DocumentTypeInconsistencyException
Same as setField(String, Object) but using the id of the field type.

This is a variant-level method.

Throws:
DocumentTypeInconsistencyException

deleteField

void deleteField(java.lang.String name)
Removes the specified field. Silently ignored if the document doesn't have that field.

This is a variant-level method.

Parameters:
name - name of the field type

deleteField

void deleteField(long fieldTypeId)
Removes the specified field. Silently ignored if the document doesn't have that field.

This is a variant-level method.


getField

Field getField(java.lang.String fieldTypeName)
               throws FieldNotFoundException
Gets a field by field type name. Throws a FieldNotFoundException if there is no such field in the document, use hasField(String) to check if the document has the field.

This is a variant-level method.

Throws:
FieldNotFoundException

getField

Field getField(long fieldTypeId)
               throws FieldNotFoundException
Same as getField(String) but using the field type id.

This is a variant-level method.

Throws:
FieldNotFoundException

hasField

boolean hasField(long fieldTypeId)
Checks if the document contains the field with the specified field type id.

This is a variant-level method.


hasField

boolean hasField(java.lang.String fieldTypeName)
Checks if the document contains the field with the specified field type name.

This is a variant-level method.


getFields

Fields getFields()
Gets all fields in the document.

This is a variant-level method.


getFieldsInOrder

Fields getFieldsInOrder()
Gets all fields in the document, sorted in the same order as the fields are defined in the document type. Any fields this document has that are not part of the document type are added in unspecified order to the end of the list.

This is a variant-level method.


save

void save()
          throws RepositoryException
Saves a document.

This is the same as calling save(boolean) with argument true.

Throws:
RepositoryException

save

void save(boolean validate)
          throws RepositoryException
Saves the document and document variant.

If only changes have been done to document-level properties, only the document will be saved. If only changes have been done to variant-level properties, only the variant will be saved.

If this is a new document, it will cause an id to be assigned to this document object.

Saving the document variant might or might not cause the creation of a new version, depending on whether any versioned data has changed. Versioned data includes the parts, fields, links and the document's name. So if for example only the retired flag changed, customfields were changed, or collection membership changed, no new version will be created. After saving, you can get the new version id from the method getLastVersionId(). The state of the new version can be influenced by using setNewVersionState(org.outerj.daisy.repository.VersionState) before calling save().

If someone else holds a pessimistic lock on the document variant, saving it will fail. Likewise, if another person saved the document since you retrieved this document object (ie a concurrent modification), saving will also fail. Note that locks apply only to document variants, so don't protect from concurrent changes to document-level properties.

Saving a document will cause the server to send out an assynchronous event, to which other processes can listen, for example the full text indexer. (There are separate events for updates to the document and the variant)

Using the argument validate you can specify whether the document variant should be validated against its document type. Usually you will always provide true here. As an example use case for not using validation, it might be that you just want to mark a document as retired without bothering that its content doesn't correspond to the schema anymore.

Throws:
RepositoryException

validate

void validate()
              throws DocumentTypeInconsistencyException
Validates that this document confirms to its document type.

Throws:
DocumentTypeInconsistencyException

setNewVersionState

void setNewVersionState(VersionState versionState)
Sets the VersionState that should be used if a new version is created when saving the document.

By default this is VersionState.PUBLISH.


getNewVersionState

VersionState getNewVersionState()
See setNewVersionState(VersionState).


lock

boolean lock(long duration,
             LockType lockType)
             throws RepositoryException
Takes a lock on the document variant. If the lock type is "pessimistic", this will prevent others from saving the document variant while you're working on it. If the lock is "warn", the lock only serves for informational purposes and will not enforce anything. So called "optimistic locking" (ie checking against concurrent modifications) happens always, and doesn't require to take a lock.

Changing a lock doesn't need a save() call afterwards, calling this method has immediate effect.

This is a variant-level method.

Parameters:
duration - indication of how long the lock should remain (in ms). Use -1 for a never-expiring lock.
Returns:
false if someone else already has a lock on this document, in which case you can call getLockInfo(boolean) with false as parameter to know who is holding the lock.
Throws:
RepositoryException

releaseLock

boolean releaseLock()
                    throws RepositoryException
Releases the lock on the document variant. This can only be done by the person holding this lock, or by an Administrator.

This is a variant-level method.

Returns:
true if the lock is removed (or if there was no lock). If a lock remains on the document, false will be returned, in which case you can call getLockInfo(boolean) with false as parameter to know who is holding the lock.
Throws:
RepositoryException

getLockInfo

LockInfo getLockInfo(boolean fresh)
                     throws RepositoryException
Returns information about the current lock on the document variant.

This is a variant-level method.

Parameters:
fresh - if true, the lock information will be refetched. Otherwise the existing information stored in this Document object will be returned (which may be out of date).
Throws:
RepositoryException

setCustomField

void setCustomField(java.lang.String name,
                    java.lang.String value)
Sets a custom field. A custom field is an arbitrary name/value pair. Custom fields are not versioned.

This is a variant-level method.


deleteCustomField

void deleteCustomField(java.lang.String name)
Removes the specified custom field. Passes silently if there is no custom field with the given name.

This is a variant-level method.


getCustomField

java.lang.String getCustomField(java.lang.String name)
Gets the value of the specified custom field, or null if there is no custom field with that name.

This is a variant-level method.


hasCustomField

boolean hasCustomField(java.lang.String name)
Returns true if there is a custom field with the specified name.

This is a variant-level method.


clearCustomFields

void clearCustomFields()
Removes all custom fields.

This is a variant-level method.


getCustomFields

java.util.Map getCustomFields()
Returns a map containing the fields, with the field type name being the key. Making changes to this map will not be reflected in the document.

This is a variant-level method.


setPart

void setPart(java.lang.String partTypeName,
             java.lang.String mimeType,
             byte[] data)
             throws DocumentTypeInconsistencyException
Sets a part.

This is a variant-level method.

Throws:
DocumentTypeInconsistencyException

setPart

void setPart(long partTypeId,
             java.lang.String mimeType,
             byte[] data)
             throws DocumentTypeInconsistencyException
Sets a part.

This is a variant-level method.

Throws:
DocumentTypeInconsistencyException

setPart

void setPart(java.lang.String partTypeName,
             java.lang.String mimeType,
             PartDataSource partDataSource)
             throws DocumentTypeInconsistencyException
Sets a part.

This is a variant-level method.

Throws:
DocumentTypeInconsistencyException

setPart

void setPart(long partTypeId,
             java.lang.String mimeType,
             PartDataSource partDataSource)
             throws DocumentTypeInconsistencyException
Sets a part.

This is a variant-level method.

Throws:
DocumentTypeInconsistencyException

setPartFileName

void setPartFileName(java.lang.String partTypeName,
                     java.lang.String fileName)
Update the file name of an already existing part. Throws an exception if the document doesn't have the indicated part.

This is a variant-level method.

Parameters:
fileName - allowed to be null (to remove the filename information)

setPartFileName

void setPartFileName(long partTypeId,
                     java.lang.String fileName)
Update the file name of an already existing part. Throws an exception if the document doesn't have the indicated part.

This is a variant-level method.

Parameters:
fileName - allowed to be null (to remove the filename information)

setPartMimeType

void setPartMimeType(java.lang.String partTypeName,
                     java.lang.String mimeType)
Update the mime-type of an already existing part. Throws an exception if the document doesn't have the indicated part.

This is a variant-level method.


setPartMimeType

void setPartMimeType(long partTypeId,
                     java.lang.String mimeType)
Update the mime-type of an already existing part. Throws an exception if the document doesn't have the indicated part.

This is a variant-level method.


deletePart

void deletePart(long partTypeId)
Removes a part, passes silently if there is no part in the document with the given id.

This is a variant-level method.


deletePart

void deletePart(java.lang.String name)
Removes a part, passes silently if there is no part in the document with the given name.

This is a variant-level method.


getPart

Part getPart(long partTypeId)
             throws PartNotFoundException
Gets a part.

This is a variant-level method.

Throws:
PartNotFoundException

getPart

Part getPart(java.lang.String name)
             throws PartNotFoundException
Gets a part.

This is a variant-level method.

Throws:
PartNotFoundException

hasPart

boolean hasPart(long partTypeId)
Checks if the document variant has the part for the specified part type.

This is a variant-level method.


hasPart

boolean hasPart(java.lang.String name)
Checks if the document variant has the part for the specified part type.

This is a variant-level method.


getParts

Parts getParts()
Returns the parts contained in the document variant, in unspecified order.


getPartsInOrder

Parts getPartsInOrder()

addLink

void addLink(java.lang.String title,
             java.lang.String target)
Adds an out-of-line link (at the end of the list).

This is a variant-level method.


deleteLink

void deleteLink(int index)
Removes an out-of-line link.

This is a variant-level method.


clearLinks

void clearLinks()
Removes all out-of-line links.

This is a variant-level method.


getLinks

Links getLinks()
Removes all out-of-line links.

This is a variant-level method.


addToCollection

void addToCollection(DocumentCollection collection)
Adds the document variant to a supplied Collection.

Parameters:
collection - the collection to add the current document to

removeFromCollection

void removeFromCollection(DocumentCollection collection)
Removes the document variant from a collection

Parameters:
collection - the collection from which the document needs to be removed

getCollections

DocumentCollections getCollections()
Returns the collections the document variant belongs to, null if the document variant belongs to no Collections.


inCollection

boolean inCollection(DocumentCollection collection)
Checks if the document variant belongs to the specified collection.


inCollection

boolean inCollection(long collectionId)
Checks if the document variant belongs to the specified collection.


getXml

org.outerx.daisy.x10.DocumentDocument getXml()
                                             throws RepositoryException
Throws:
RepositoryException

getXmlWithoutVariant

org.outerx.daisy.x10.DocumentDocument getXmlWithoutVariant()
                                                           throws RepositoryException
Throws:
RepositoryException

getXmlWithoutVersionedData

org.outerx.daisy.x10.DocumentDocument getXmlWithoutVersionedData()
                                                                 throws RepositoryException
Throws:
RepositoryException

getXml

org.outerx.daisy.x10.DocumentDocument getXml(long versionId)
                                             throws RepositoryException
Gets the XML of the document but include the data from the specified version, instead of the current data. This only applies to the data of the document that is actually versionable, of course. For the rest of the data, you'll get what's currently in the document object, whether that data has already been saved or not.

Throws:
RepositoryException

clearCollections

void clearCollections()
Removes the document variant from all the collections it belongs to.


getSummary

java.lang.String getSummary()
Returns a summary text for the document variant. The summary is only created/updated when the document is saved. Returns an empty string if there's no summary. The summary always corresponds to the live version of the document.


getVariantCreatedFromBranchId

long getVariantCreatedFromBranchId()
If the variant currently loaded in this document object is created from an existing branch, this method will return the id of that branch, otherwise it will return -1. Note that the branch could possibly no longer exist.


getVariantCreatedFromLanguageId

long getVariantCreatedFromLanguageId()
Similar to getVariantCreatedFromBranchId().


getVariantCreatedFromVersionId

long getVariantCreatedFromVersionId()
Similar to getVariantCreatedFromBranchId().


getUpdateCount

long getUpdateCount()

getVariantUpdateCount

long getVariantUpdateCount()


Copyright © -2012 . All Rights Reserved.