//============================================================================== // Folder.java //============================================================================== package tribble.repository; import java.io.Closeable; import java.io.InputStream; import java.io.IOException; import java.lang.Exception; import java.lang.String; /******************************************************************************* * Generic read-only repository document folder. * *

* A repository folder contains zero or more repository documents. * *

* A repository folder has an identifying folder ID which provides a * means for locating it within the repository system. This is generally some * kind of identifier string that uniquely designates a single folder within the * repository with respect to the context that the repository is being accessed * (i.e., with respect to the configuration properties that were use to * initialize and open the repository handler). * *

* A repository folder may also possess a size, which specifies the * number of documents currently residing in the folder. Note that this * information might not be available in all implementations. * *

* Each repository folder has a set of zero or more default * document properties associated with it. These properties * ({@link DocumentProperty} objects) specify default attributes of the documents * contained within the folder; these default properties are inherited by * documents as they are added into the repository folder (unless overridden by * the {@link RepositoryWriter}). * *

* Note: This requires Java 1.5 or later. * * *

*
Source code:
*
* http://david.tribble.com/src/java/tribble/repository/Folder.java *
*
Documentation:
*
* http://david.tribble.com/docs/tribble/repository/Folder.html *
*
* * * @version API 3.0, $Revision: 1.1 $ $Date: 2012/03/17 22:54:15 $ * @since 2012-02-05 * @author David R. Tribble (david@tribble.com)
* Copyright ©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 Document * @see DocumentProperty * @see RepositoryReader * @see RepositoryWriter */ public interface Folder extends java.io.Closeable { static final String REV = "@(#)tribble/repository/Folder.java $Revision: 1.1 $ $Date: 2012/03/17 22:54:15 $\n"; // ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ // Methods /*************************************************************************** * Close this repository folder. * Deallocates all resources associated with the folder. * Any further use of the folder will result in exceptions. * *

* Note that this method does not throw any exceptions. * *

* Implementations may allow this method to be called more than once. * * @since API 3.0, 2012-02-05 */ //@Override public abstract void close(); /*************************************************************************** * Retrieve the repository that contains this document folder. * * @return * The parent repository for this folder, or null if it does not have a * parent. * * @throws IOException * Thrown if an error occurred while accessing the folder. * * @since API 3.0, 2012-02-16 */ public abstract Repository getRepository() throws IOException; /*************************************************************************** * Retrieve the ID of this repository folder. * * @return * A name that identifies the folder within the repository. * * @throws IOException * Thrown if an error occurred while accessing the folder. * * @since API 3.0, 2012-02-05 */ public abstract String getID() throws IOException; /*************************************************************************** * Retrieve the number of documents currently in this repository folder. * * @return * The number of documents, or -1 if the count cannot be determined. * * @throws IOException * Thrown if an error occurred while accessing the folder. * * @since API 3.0, 2012-02-05 */ public abstract long getDocumentCount() throws IOException; /*************************************************************************** * Retrieve the value of a default document property in this repository * folder. * * @param prop * The name of the document property value to retrieve. * * @return * The default property value (which may be null). * * @throws IOException * Thrown if an error occurred while accessing the folder, or * if the folder does not have the specified property. * * @since API 3.0, 2012-02-05 */ public abstract Object getDefaultProperty(String prop) throws IOException; /*************************************************************************** * Retrieve the default document properties associated with this repository * folder. * * @return * The default document properties defined for this folder. * * @throws IOException * Thrown if an error occurred while accessing the folder. * * @since API 3.0, 2012-02-05 */ public abstract DocumentProperty[] getDefaultProperties() throws IOException; /*************************************************************************** * Retrieve a specific document from this repository folder. * * @param id * ID of the document to retrieve from the folder. * * @return * The specified document, or null if no such document exists within the * repository folder. * * @throws IOException * Thrown if an error occurs while accessing the repository folder. * * @throws IllegalStateException (unchecked) * Thrown if {@link #initialize initialize()} has not been called yet. * * @since API 3.0, 2012-02-05 */ public abstract DocType getDocument(String id) throws IOException; /*************************************************************************** * Find matching documents within this repository folder. * * @param query * A query for searching for multiple matching documents within the * repository folder. The actual form of this object (string, expression * tree, etc.) is dependent upon the implementation of the repository system. * This may be a subtype that implements interface {@link DocumentFilter}. * * @return * A set of zero or more matching documents. * * @throws IOException * Thrown if an error occurs while accessing the repository folder. * * @throws IllegalStateException (unchecked) * Thrown if the folder is no longer open. * * @since API 3.0, 2012-02-05 */ public abstract DocumentIterator findDocuments(Object query) throws IOException; } // End Folder.java