com.xerox.bantam
Interface Document

All Known Subinterfaces:

CollectionDocument, ContentDocument

All Known Implementing Classes:

AbstractDocument

public interface Document

Root Document interface. A Document is the fundamental unit managed by a Storage. A Document may have an arbitrary number of named properties, each with one or more values. The numbers and types of values of various properties may be constrained by schema restrictions enforced for the Storage instance. A Document may have an arbitrary number of schemas enforced upon it, and the set of enforced schemas may be changed at any time. While a schema is enforced upon a Document, the implementation must guarantee that the document has all non-optional properties of the schema and that the schema restrictions on numbers and types of values are enforced. In the absence of any schema restrictions for a particular property, a document may have one or more values of the property and the values may be of any Serializable Java type. All values of a particular property on a particular document must have the same type. Having zero values of a property is equivalent to not having the property. Java null is never a legal property value. A Storage implementation has flexibility in how values are stored, and will not necessarily use the standard serialized representation in all cases, though it must be capable of restoring an equivalent value.

Note that it is possible to store an arbitrary serializable collection of Java objects as a value of a property. Such objects are always treated as opaque single values of a property and are not subject to any form of containment query.

A Document object obtained from a Storage implementation may be used as a property value to link documents.

For programmer convenience, methods are provided in the Document interface for simple access to single-valued properties. These methods may only be used in a single-valued context, meaning one of the following must hold:

• An enforced schema constraint restricts the number of values of the property to 1.
• There is no enforced schema constraint for the property but it currently has at most one value on the document.

Any attempt to use one of the single-value convenience methods outside of a single-valued context will cause an exception to be thrown. For example, calling setPropertyValue() for a property with a schema constraint that permits multiple values will cause an exception even if the property is unset on the document. In this situation, calling getPropertyValue() will throw an exception even if the document happens to have only one value for the property at the time.

Applications should use the single-valued interfaces only in those situations where the property is guaranteed to be single-valued, which is exactly when a schema enforces a maximum of 1 value.

Version:

$Revision: 1.10 $, $Date: 2000/06/30 02:59:42 $

Author:

Keith Edwards, Jim Thornton

Method Summary

void	addMultiValue(FieldDescriptor desc, Serializable value) Adds property value by field descriptor.
void	addMultiValue(String name, Serializable value) Adds property value.
boolean	clearProperty(FieldDescriptor desc) Remove any and all values of a property by field descriptor.
boolean	clearProperty(String name) Remove any and all values of a property.
boolean	conformsTo(Schema schema) Determine whether the document conforms to the specified schema.
boolean	containsValue(FieldDescriptor desc, Serializable val) Determines whether specified value is one of the values of the property
boolean	containsValue(String name, Serializable val) Determines whether specified value is one of the values of the property
void	delete() Delete the document.
void	enforceSchema(Schema schema) Enforce the specified schema on the document.
void	enforceSchema(Schema schema, Map props) Enforce the specified schema on the document.
void	flush() Force any recent changes to this document to be written to stable storage immediately.
String[]	get_all_property_names() Get names of all set properties, including internal properties.
FieldDescriptor[]	getDescriptors(Schema schema) Get descriptors of set properties from a schema.
Schema[]	getEnforcedSchemas() Get all schemas enforced on the document.
String	getID() Get the document's unique ID.
Collection	getMultiValues(FieldDescriptor desc) Gets the values of a property by field descriptor.
Collection	getMultiValues(String name) Gets the values of a property.
String	getName() Return a canonical "name" value that can be displayed along with the document.
String[]	getPropertyNames() Get names of set properties.
String[]	getPropertyNames(String prefix) Get names of set properties with the supplied property name prefix.
Object	getPropertyValue(FieldDescriptor desc) Returns the value of a single-valued property by field descriptor.
Object	getPropertyValue(String name) Returns the value of a single-valued property if set, or null otherwise.
Storage	getStorage() Return the storage object associated with this document.
String[]	getUnenforcedPropertyNames(String prefix) Get names of set properties that do not belong to an enforced schema.
boolean	isEnforced(Schema schema) Determine whether the specified schema is currently enforced on the document.
boolean	propertyExists(FieldDescriptor desc) Determines whether the property is set by field descriptor.
boolean	propertyExists(String name) Determines whether the property is set.
boolean	removeValue(FieldDescriptor desc, Serializable value) Removes a property value if present by field descriptor.
boolean	removeValue(String name, Serializable value) Removes a property value if present.
void	setMultiValues(FieldDescriptor desc, Collection values) Sets the values of property by field descriptor.
void	setMultiValues(String name, Collection values) Sets the values of property.
void	setName(String name) Set the canonical name of the document.
void	setPropertyValue(FieldDescriptor desc, Serializable value) Sets the value of a single-valued property by field descriptor.
void	setPropertyValue(String name, Serializable value) Set the value of a single-valued property.
boolean	unenforceSchema(Schema schema) Stop enforcing the specified schema on the document.

Method Detail

getID

public String getID()

Get the document's unique ID.

Returns:

ID of the document

getStorage

public Storage getStorage()

Return the storage object associated with this document.

Returns:

Storage object for the document

getName

public String getName()

Return a canonical "name" value that can be displayed along with the document. If a canonical name value has been set with setName(), then that value will be returned, otherwise some implementation-specific value will be returned, possibly the value of some property, possibly a descriptive string or some representation of the document ID.

Returns:

canonical name of document

setName

public void setName(String name)
             throws StorageException

Set the canonical name of the document. This name will be returned by subsequent calls to getName(). The name value may also be set as the value of some property on the document.

Parameters:

name - Name of document

flush

public void flush()
           throws StorageException

Force any recent changes to this document to be written to stable storage immediately. Implementations are free to delay writes in order to improve application performance. By calling this method an application can request that any dirty data held in implementation caches for this document be immediately committed to stable storage. Some implementations may be incapable of forcing immediate writes and will throw an exception whenever this method is invoked. There are two reasons why an application may want to ensure that changes have reached stable storage. First, the application may need to ensure that critical data cannot be lost after submission. Secondly, an application may need to ensure that another process using the same document base gains access to changes as quickly as possible. Application developers should not assume to much from this feature, as Bantam does not mandate strong guarantees of transactional semantics and the effect of this method will vary by implementation. In particular, an implementation is free to flush all dirty data for all documents when this method is called on any individual document.

Throws:

StorageException - if the implementation does not support flush or encounters an error on writing

delete

public void delete()
            throws StorageException

Delete the document. If successful, this operation invalidates the object causing all subsequent operations to throw exceptions or return undefined results.

getEnforcedSchemas

public Schema[] getEnforcedSchemas()
                            throws StorageException

Get all schemas enforced on the document.

Returns:

Array of schemas enforced on this document.

enforceSchema

public void enforceSchema(Schema schema)
                   throws StorageException

Enforce the specified schema on the document. The document must conform to the schema at the time this method is called, or an exception will be thrown.

Parameters:

schema - The schema to enforce

Throws:

StorageException - if the document does not conform to schema

enforceSchema

public void enforceSchema(Schema schema,
                          Map props)
                   throws StorageException

Enforce the specified schema on the document. As a convenience, this method can be supplied with property values required to make the document conform to the schema so that enforcement is possible. Note that it is not possible to use this method to set multiple values of a property, but it is possible to set a single value, ensuring that a required property is set. Alternatively, the document may be made to conform to the schema first using the regular methods for setting values, and then this method may be called without a property values Map by passing null for the props parameter, or using the single-argument version.

Parameters:

schema - The schema to enforce

props - Map supplying (property id,value) pairs to satisfy the requirements of the enforced schema, where id is a String property name or a FieldDescriptor name or a FieldDescriptor reference to a property.

unenforceSchema

public boolean unenforceSchema(Schema schema)
                        throws StorageException

Stop enforcing the specified schema on the document. If the schema is not currently enforced on the document then this operation has no effect. This operation does not affect the property values of the document, so if the schema is enforced at the time of the call, the document will still conform to the schema after the call.

Parameters:

schema - the schema that is not to be enforced

Returns:

true if the schema was enforced prior to the call, false otherwise

isEnforced

public boolean isEnforced(Schema schema)
                   throws StorageException

Determine whether the specified schema is currently enforced on the document.

Parameters:

schema - the schema to check

Returns:

true if schema is currently enforced on document, false otherwise

conformsTo

public boolean conformsTo(Schema schema)
                   throws StorageException

Determine whether the document conforms to the specified schema. Note that a document may conform to a schema, that is satisfy the requirements of a schema, even when the schema is not enforced. Without enforcement, however, the system will not prevent changes to properties that would cause a conforming document to become non-conforming. If a document conforms to a schema, then the schema may be immediately enforced without making any changes to properties, meaning enforceSchema() may be called with a null value for props.

Parameters:

schema - the schema to check

Returns:

true if the document currently conforms to the schema

setPropertyValue

public void setPropertyValue(String name,
                             Serializable value)
                      throws StorageException

Set the value of a single-valued property. This method may only be used in a single-valued context as defined above.

Parameters:

name - name of property to set

value - value to set

setPropertyValue

public void setPropertyValue(FieldDescriptor desc,
                             Serializable value)
                      throws StorageException

Sets the value of a single-valued property by field descriptor. This method may only be used in a single-valued context as defined above.

Parameters:

desc - field descriptor identifying a property

value - value to set

getPropertyValue

public Object getPropertyValue(String name)
                        throws StorageException

Returns the value of a single-valued property if set, or null otherwise. This method may only be used in a single-valued context as defined above.

Parameters:

name - name of property

Returns:

value of property if set, null otherwise

getPropertyValue

public Object getPropertyValue(FieldDescriptor desc)
                        throws StorageException

Returns the value of a single-valued property by field descriptor. This method may only be used in a single-valued context as defined above. This call typechecks the value against the field descriptor, and will raise an exception if the property doesn't exist (and the descriptor is not optional) or if its type doesn't match.

Parameters:

desc - field descriptor identifying a property

Returns:

value of property if set, null otherwise

setMultiValues

public void setMultiValues(String name,
                           Collection values)
                    throws StorageException

Sets the values of property. Any existing values of this property are replaced by this call. Each individual value must be an object of type Serializable and non-null. The collection object itself is not stored, nor are its semantics preserved in any way, only the objects returned by the collection iterator are stored. This method may be used to set a single value by passing a Collection containing only one element.

Parameters:

name - the property name

values - a collection containing the values to set

setMultiValues

public void setMultiValues(FieldDescriptor desc,
                           Collection values)
                    throws StorageException

Sets the values of property by field descriptor.

Parameters:

desc - field descriptor identifying a property

values - a collection containing the values to set

addMultiValue

public void addMultiValue(String name,
                          Serializable value)
                   throws StorageException

Adds property value. Any existing values of this property are unaffected by this call. The value must be non-null. This method may be used to set a single value if the property is unset at the time of the call.

Parameters:

name - name of property

value - the value to add

addMultiValue

public void addMultiValue(FieldDescriptor desc,
                          Serializable value)
                   throws StorageException

Adds property value by field descriptor.

Parameters:

desc - field descriptor identifying a property

value - the value to add

getMultiValues

public Collection getMultiValues(String name)
                          throws StorageException

Gets the values of a property. The values are conveyed through a Collection object, but although changes may not cause an exception they will never have any effect on the document property. The Collection is just a container. When applied to a single-valued property, the result Collection will contain only one value.

Parameters:

name - the name of the property

Returns:

Collection containing all values of the property.

getMultiValues

public Collection getMultiValues(FieldDescriptor desc)
                          throws StorageException

Gets the values of a property by field descriptor.

Parameters:

desc - field descriptor identifying a property

Returns:

Collection containing all values of the property.

containsValue

public boolean containsValue(FieldDescriptor desc,
                             Serializable val)
                      throws StorageException

Determines whether specified value is one of the values of the property

Parameters:

desc - field descriptor identifying a property

val - a value to test

Returns:

true if val is one of values of identified property

containsValue

public boolean containsValue(String name,
                             Serializable val)
                      throws StorageException

Determines whether specified value is one of the values of the property

Parameters:

name - name of a property

val - a value to test

Returns:

true if val is one of values of identified property

removeValue

public boolean removeValue(String name,
                           Serializable value)
                    throws StorageException

Removes a property value if present. If the value occurs multiple times in the bag of values of the property, then this call removes only one value instance. If the value is not present then this call has no effect.

Parameters:

name - the name of the property.

Returns:

true if a value was removed, false otherwise

removeValue

public boolean removeValue(FieldDescriptor desc,
                           Serializable value)
                    throws StorageException

Removes a property value if present by field descriptor.

Parameters:

desc - field descriptor identifying a property

Returns:

true if a value was removed, false otherwise

clearProperty

public boolean clearProperty(String name)
                      throws StorageException

Remove any and all values of a property. When applied to either a single-valued or multi-valued property, this method unsets the property.

Parameters:

name - the name of the property

Returns:

true if the property was set, false otherwise

clearProperty

public boolean clearProperty(FieldDescriptor desc)
                      throws StorageException

Remove any and all values of a property by field descriptor.

Parameters:

desc - field descriptor identifying a property

Returns:

true if the property was set, false otherwise

propertyExists

public boolean propertyExists(String name)
                       throws StorageException

Determines whether the property is set. A property is set if it has at least one value.

Parameters:

name - the name of the property

Returns:

true if the property is set, false otherwsie.

propertyExists

public boolean propertyExists(FieldDescriptor desc)
                       throws StorageException

Determines whether the property is set by field descriptor.

Parameters:

desc - field descriptor identifying property

Returns:

true if the property is set, false otherwsie.

getPropertyNames

public String[] getPropertyNames()
                          throws StorageException

Get names of set properties.

Returns:

array of property names

getPropertyNames

public String[] getPropertyNames(String prefix)
                          throws StorageException

Get names of set properties with the supplied property name prefix.

Parameters:

prefix - the prefix

Returns:

array of property names

getUnenforcedPropertyNames

public String[] getUnenforcedPropertyNames(String prefix)
                                    throws StorageException

Get names of set properties that do not belong to an enforced schema.

Parameters:

prefix - prefix to filter with or null

Returns:

array of property names

getDescriptors

public FieldDescriptor[] getDescriptors(Schema schema)
                                 throws StorageException

Get descriptors of set properties from a schema. This method returns the descriptors of properties mentioned in the supplied schema that are presently set on the document. It does not matter whether or not the supplied schema is presently enforced on the document, but if it is unenforced then descriptors for schema-required properties may be absent from the result.

Parameters:

schema - the schema to check

Returns:

array of descriptors of set properties from schema

get_all_property_names

public String[] get_all_property_names()
                                throws StorageException

Get names of all set properties, including internal properties. The result of this call is implementation dependent. Some implementations may maintain some hidden or system properties which are not exposed through getPropertyNames(). This method may be used to request the names of all properties, including those not set by applications. An implementation may enforce unspecified restrictions on internal properties, such as limitations on reading or writing, so using other Document methods with these properties may cause exceptions or undefined behavior. The only requirements are that propertyExists() must return true for any name returned by this method, and propertyExists() must return false for any name not returned by this method. This method may return property names not returned by any of the other methods that get set property information but it may also return results identical to the zero argument form of getPropertyNames().