//==============================================================================
// DocumentProperty.java
//==============================================================================
package tribble.repository;
import java.io.IOException;
import java.lang.Exception;
import java.lang.IllegalArgumentException;
import java.lang.IllegalStateException;
import java.lang.NullPointerException;
import java.lang.Object;
import java.lang.String;
/*******************************************************************************
* Generic document property.
*
*
* This class provides the fundamental attributes and methods for a
* document property that is associated with a repository document.
*
*
* A repository document is composed of content data (such as an image,
* text, or other kind of user data) and zero or more properties.
* Typically, the properties comprise the keys used to store the document in a
* document storage system. Typically, all of the documents within a repository
* system share the same set of document properties, although this is not
* required of any implementation.
*
*
* Document properties specify attributes of the document beyond the content data
* of the document, the meaning of which are defined by the implementation.
* For example, a given implementation might provide properties specifying things
* like a document's modification date, number of pages it contains, the names of
* its authors, its access permissions, its expiration date, an identification
* number shared by other related documents within the same batch, and so forth.
* In addition to the document ID, one or more of these properties might be
* used as keys to store the document in the repository system.
*
*
* Each document property has the following attributes:
*
* - name
* - type
* - length
* - input (source) format
* - output (repository) format
* - default value
*
*
*
* There may be other attributes of the properties, which are specific to the
* particular subclass implementation of the repository system.
* For documents being written to a repository by an {@link RepositoryWriter},
* a property can be associated with the document using the
* {@link StorableDocument#addProperty StorableDocument.addProperty()}
* method (or by some other means provided by the implementation).
*
*
* A given property that is associated with a particular repository document also
* has a value, which is an object of some sort. Once a property is
* associated with the document, its value can be set to some object using the
* {@link StorableDocument#setProperty StorableDocument.setProperty()} method.
* The values of the properties can be accessed for a given document that was
* retrieved by an {@link RepositoryReader}, by calling the
* {@link Document#getProperty Document.getProperty()} method.
*
*
* The value of a property is the minimum amount of information that is
* useful to an implementation. The other attributes may be used or ignored by
* the implementation as it deems necessary.
*
*
* Note: This requires Java 1.5 or later.
*
*
*
* - Source code:
* -
* http://david.tribble.com/src/java/tribble/repository/DocumentProperty.java
*
* - Documentation:
* -
* http://david.tribble.com/docs/tribble/repository/DocumentProperty.html
*
*
*
*
* @version API 3.0, $Revision: 1.3 $ $Date: 2012/03/17 23:01:22 $
* @since 2008-04-03
* @author David R. Tribble (david@tribble.com)
* Copyright ©2008-2012 by David R. Tribble, all rights reserved.
* Permission is granted to any person or entity except those designated
* by the United States Department of State as a terrorist or terrorist
* government or agency, to use and distribute this source code provided
* that the original copyright notice remains present and unaltered.
*
* @see WritableProperty
* @see Document
*/
public class DocumentProperty
{
static final String REV =
"@(#)tribble/repository/DocumentProperty.java $Revision: 1.3 $ $Date: 2012/03/17 23:01:22 $\n";
// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
// Constants
//----------------------------------
// Property types
/** Property type: Alphanumeric text. */
public static final String TYPE_TEXT = "java.lang.String";
/** Property type: Binary data. */
public static final String TYPE_BINARY = "byte[]";
/** Property type: Numeric. */
public static final String TYPE_NUM = "int";
/** Property type: Date/time. */
public static final String TYPE_DATE = "java.util.Date";
/** Property type: Filename. */
public static final String TYPE_FILE = "java.io.File";
// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
// Variables
/** Property name. */
protected String m_name;
/** Property type.
* This can be one of the {@link #TYPE_TEXT TYPE_XXX} constants
* or some other application-defined value.
*/
protected String m_type;
/** Text property length. */
protected int m_len;
/** Output format. */
protected String m_outFmt;
/** Input format. */
protected String m_inFmt;
/** Default output value. */
protected Object m_dflVal;
/** Property is modifiable. */
protected boolean m_writable;
// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
// Constructors
/**************************************************************************
* Constructor.
*
* @param name
* The name of this document property.
* This cannot be null or empty.
*
* @throws NullPointerException (unchecked)
* Thrown if name is null.
*
* @throws IllegalArgumentException (unchecked)
* Thrown if name is an empty string ("").
*
* @since API 2.0, 2008-04-03
*/
public DocumentProperty(String name)
{
// Initialize
if (name == null)
throw new NullPointerException();
if (name.length() == 0)
throw new IllegalArgumentException();
m_name = name;
}
/**************************************************************************
* Constructor.
*
* @param name
* The name of this document property.
* This cannot be null or empty.
*
* @param type
* Property type. This can be one of the {@link #TYPE_TEXT TYPE_XXX}
* constants or some other application-defined value (e.g., a MIME type
* name).
*
* @param len
* Text property length.
*
* @param outFmt
* Output format.
*
* @param inFmt
* Input format.
*
* @param dflVal
* Default output value.
*
* @throws NullPointerException (unchecked)
* Thrown if name is null.
*
* @throws IllegalArgumentException (unchecked)
* Thrown if name is an empty string ("").
*
* @since API 2.0, 2008-04-19
*/
public DocumentProperty(String name, String type, int len,
String outFmt, String inFmt, Object dflVal)
{
// Initialize
this(name);
m_type = type;
m_len = len;
m_outFmt = outFmt;
m_inFmt = inFmt;
m_dflVal = dflVal;
}
// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
// Methods
/***************************************************************************
* Compares two objects for equality.
* Document properties are considered equal if they have the same name.
*
* @param obj
* The object to compare this object to.
*
* @return
* True if these objects are equal, false otherwise.
*
* @since API 2.0, 2008-04-03
*/
@Override
public boolean equals(Object obj)
{
if (obj == null)
return false;
if (obj == this)
return true;
if (obj instanceof DocumentProperty)
return ((DocumentProperty) obj).m_name.equals(this.m_name);
return false;
}
/***************************************************************************
* Generates a hash code for this property.
*
* @return
* An integer hash code for this property.
*
* @since API 2.0, 2008-04-03
*/
@Override
public int hashCode()
{
return m_name.hashCode();
}
/***************************************************************************
* Retrieve the name of this document property.
*
* @return
* The name of this property.
*
* @since API 2.0, 2008-04-03
*/
public String getName()
{
return m_name;
}
/***************************************************************************
* Retrieve the type of this document property.
*
* @return
* The type of this property, which is one of the
* {@link #TYPE_TEXT TYPE_XXX} constants or some other
* application-defined value (e.g., a MIME type name),
* or null if it is not defined.
*
* @since API 2.0, 2008-04-03
*/
public String getType()
{
return m_type;
}
/***************************************************************************
* Establish the type of this document property.
*
* @param type
* The type of this property, which is one of the
* {@link #TYPE_TEXT TYPE_XXX} constants or some other
* application-defined value (e.g., a MIME type name),
* or null if it is not defined.
*
* @throws IllegalStateException (unchecked)
* Thrown if this document property is not modifiable.
*
* @since API 2.0, 2008-04-22
*/
public void setType(String type)
{
if (!m_writable)
throw new IllegalStateException(
"Document property is not modifiable");
m_type = type;
}
/***************************************************************************
* Retrieve the length of this document property.
*
* @return
* The length of this document property, or zero if it is not defined.
*
* @since API 2.0, 2008-04-03
*/
public int getLength()
{
return m_len;
}
/***************************************************************************
* Establish the length of this document property.
*
* @param len
* The length of this document property, or zero if it is not defined.
*
* @throws IllegalStateException (unchecked)
* Thrown if this document property is not modifiable.
*
* @since API 2.0, 2008-04-22
*/
public void setLength(int len)
{
if (!m_writable)
throw new IllegalStateException(
"Document property is not modifiable");
m_len = len;
}
/***************************************************************************
* Retrieve the output format specification for this document property.
*
* @return
* The formatting specification of this property, which specifies how the
* property value should be formatted when it is stored in a repository
* document; or null if it is not defined.
*
* @since API 2.0, 2008-04-03
*/
public String getOutputFormat()
{
return m_outFmt;
}
/***************************************************************************
* Establish the output format specification for this document property.
*
* @param fmt
* The formatting specification of this property, which specifies how the
* property value should be formatted when it is stored in a repository
* document; or null if it is not defined.
*
* @throws IllegalStateException (unchecked)
* Thrown if this document property is not modifiable.
*
* @since API 2.0, 2008-04-22
*/
public void setOutputFormat(String fmt)
{
if (!m_writable)
throw new IllegalStateException(
"Document property is not modifiable");
m_outFmt = fmt;
}
/***************************************************************************
* Retrieve the input (source) format specification for this document
* property.
*
* @return
* The source formatting specification of this property, which specifies the
* format of the property value before it is stored in a repository document
* (i.e., it specifies how the source value for this property should be
* unformatted when its value is set, prior to being
* reformatted when it is written to the repository);
* or null if it is not defined.
*
* @since API 2.0, 2008-04-03
*/
public String getInputFormat()
{
return m_inFmt;
}
/***************************************************************************
* Establish the input (source) format specification for this document
* property.
*
* @param fmt
* The source formatting specification of this property, which specifies the
* format of the property value before it is stored in a repository document
* (i.e., it specifies how the source value for this property should be
* unformatted when its value is set, prior to being
* reformatted when it is written to the repository);
* or null if it is not defined.
*
* @throws IllegalStateException (unchecked)
* Thrown if this document property is not modifiable.
*
* @since API 2.0, 2008-04-22
*/
public void setInputFormat(String fmt)
{
if (!m_writable)
throw new IllegalStateException(
"Document property is not modifiable");
m_inFmt = fmt;
}
/***************************************************************************
* Retrieve the default value for this document property.
*
* @return
* The default value to be used by this document property if it is not
* explicitly set to another value. This is null if the property has no
* default value established.
*
* @since API 2.0, 2008-04-03
*/
public Object getDefaultValue()
{
return m_dflVal;
}
/***************************************************************************
* Establish the default value for this document property.
* If this method is not called, the default value is null.
*
* @param val
* The default value to be used by this document property if it is not
* explicitly set to another value. This can be null.
*
* @throws IllegalStateException (unchecked)
* Thrown if this document property is not modifiable.
*
* @since API 2.0, 2008-04-22
*/
public void setDefaultValue(Object val)
{
if (!m_writable)
throw new IllegalStateException(
"Document property is not modifiable");
m_dflVal = val;
}
}
// End DocumentProperty.java