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

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


getBranchId

public long getBranchId()

getLanguageId

public long getLanguageId()

getVariantKey

public VariantKey getVariantKey()

isVariantNew

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


getAvailableVariants

public 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

public 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

public 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

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

Throws:
RepositoryException

getName

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

The document name is a variant-level property.


setName

public 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

public 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

public 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

public 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

public 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

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

This is a document-level property.


isRetired

public 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

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

This is a variant-level property.


getLastModified

public 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

public 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

public 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

public 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

public 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

public 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

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

This is a variant-level property.


getLastVersion

public 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

public 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

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

This is a variant-level method.


canReadLiveOnly

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


setField

public 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).
Throws:
DocumentTypeInconsistencyException

setField

public 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

public 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

public 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

public 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

public 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

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

This is a variant-level method.


hasField

public 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

public Fields getFields()
Gets all fields in the document.

This is a variant-level method.


getFieldsInOrder

public 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

public void save()
          throws RepositoryException
Saves a document.

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

Throws:
RepositoryException

save

public 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

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

Throws:
DocumentTypeInconsistencyException

setNewVersionState

public 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

public VersionState getNewVersionState()
See setNewVersionState(VersionState).


lock

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public void clearCustomFields()
Removes all custom fields.

This is a variant-level method.


getCustomFields

public 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

public 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

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

This is a variant-level method.

Throws:
DocumentTypeInconsistencyException

setPart

public 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

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

This is a variant-level method.

Throws:
DocumentTypeInconsistencyException

setPartFileName

public 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

public 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

public 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

public 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

public 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

public 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

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

This is a variant-level method.

Throws:
PartNotFoundException

getPart

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

This is a variant-level method.

Throws:
PartNotFoundException

hasPart

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

This is a variant-level method.


hasPart

public 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

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


getPartsInOrder

public Parts getPartsInOrder()

addLink

public 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

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

This is a variant-level method.


clearLinks

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

This is a variant-level method.


getLinks

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

This is a variant-level method.


addToCollection

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

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

removeFromCollection

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

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

getCollections

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


inCollection

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


inCollection

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


getXml

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

getXmlWithoutVariant

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

getXmlWithoutVersionedData

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

getXml

public 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

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


getSummary

public 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

public 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

public long getVariantCreatedFromLanguageId()
Similar to getVariantCreatedFromBranchId().


getVariantCreatedFromVersionId

public long getVariantCreatedFromVersionId()
Similar to getVariantCreatedFromBranchId().


getUpdateCount

public long getUpdateCount()

getVariantUpdateCount

public long getVariantUpdateCount()


Copyright © -2005 . All Rights Reserved.