//============================================================================== // 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: *

* *

* 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