001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: *
017: */
018:
019: /* $Id: Collection.java 536600 2007-05-09 17:48:31Z andreas $ */
020:
021: package org.apache.lenya.modules.collection;
022:
023: import org.apache.lenya.cms.publication.Document;
024: import org.apache.lenya.cms.publication.DocumentException;
025:
026: /**
027: * A document representing a collection of documents.
028: * This class is in prototyping stage.
029: */
030: public interface Collection {
031:
032: /** collection namespace */
033: String NAMESPACE = "http://apache.org/cocoon/lenya/collection/1.0";
034:
035: /** default namespace prefix */
036: String DEFAULT_PREFIX = "col";
037:
038: /** document element */
039: String ELEMENT_COLLECTION = "collection";
040:
041: /** element for single document references */
042: String ELEMENT_DOCUMENT = "document";
043:
044: /** attribute for document IDs */
045: String ATTRIBUTE_UUID = "uuid";
046:
047: /**
048: * Name of the type attribute.
049: */
050: String ATTRIBUTE_TYPE = "type";
051:
052: /**
053: * Name of the href attribute.
054: */
055: String ATTRIBUTE_HREF = "href";
056:
057: /**
058: * Returns the documents in this collection.
059: * @return An array of documents.
060: * @throws DocumentException when something went wrong.
061: */
062: Document[] getDocuments() throws DocumentException;
063:
064: /**
065: * Adds a document to the collection.
066: * @param document A document.
067: * @throws DocumentException when an error occurs.
068: */
069: void add(Document document) throws DocumentException;
070:
071: /**
072: * Inserts a document into the collection at a specific position.
073: * @param document A document.
074: * @param position The position of the document after insertion,
075: * starting with 0.
076: * @throws DocumentException when something went wrong.
077: */
078: void add(int position, Document document) throws DocumentException;
079:
080: /**
081: * Removes a document from the collection.
082: * @param document A document.
083: * @throws DocumentException when the document is not contained
084: * or another error occurs.
085: */
086: void remove(Document document) throws DocumentException;
087:
088: /**
089: * Removes all documents from this collection.
090: * @throws DocumentException when something went wrong.
091: */
092: void clear() throws DocumentException;
093:
094: /**
095: * Checks if this collection contains a specific document.
096: * @param document The document to check.
097: * @return A boolean value.
098: * @throws DocumentException when something went wrong.
099: */
100: boolean contains(Document document) throws DocumentException;
101:
102: /**
103: * Returns the first position of this document in the collection.
104: * @param document The document.
105: * @return An integer.
106: * @throws DocumentException when the document is not contained.
107: */
108: int getFirstPosition(Document document) throws DocumentException;
109:
110: /**
111: * Returns the number of documents in this collection.
112: * @return An integer value.
113: * @throws DocumentException when something went wrong.
114: */
115: int size() throws DocumentException;
116:
117: /**
118: * @return The document which the collection is stored in.
119: */
120: Document getDelegate();
121:
122: /**
123: * Type for automatic inclusion of child documents.
124: */
125: String TYPE_CHILDREN = "children";
126:
127: /**
128: * Type for manual addition of documents.
129: */
130: String TYPE_MANUAL = "manual";
131:
132: /**
133: * Type for manual addition of documents.
134: */
135: String TYPE_LINK = "link";
136:
137: /**
138: * @param type One of {@link #TYPE_CHILDREN}, {@link #TYPE_MANUAL}, {@link #TYPE_LINK}.
139: */
140: void setType(String type);
141:
142: /**
143: * @return One of {@link #TYPE_CHILDREN}, {@link #TYPE_MANUAL}, {@link #TYPE_LINK}.
144: */
145: String getType();
146:
147: /**
148: * @return The link target.
149: */
150: String getHref();
151:
152: /**
153: * @param href The link target. If the type is not {@link #TYPE_LINK}, calling
154: * this method has no effect.
155: */
156: void setHref(String href);
157: }
|