001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
003: * Distributed under the terms of either:
004: * - the common development and distribution license (CDDL), v1.0; or
005: * - the GNU Lesser General Public License, v2.1 or later
006: * $Id: ContentStore.java 3634 2007-01-08 21:42:24Z gbevin $
007: */
008: package com.uwyn.rife.cmf.dam;
009:
010: import com.uwyn.rife.cmf.Content;
011: import com.uwyn.rife.cmf.ContentInfo;
012: import com.uwyn.rife.cmf.MimeType;
013: import com.uwyn.rife.cmf.dam.exceptions.ContentManagerException;
014: import com.uwyn.rife.cmf.format.Formatter;
015: import com.uwyn.rife.cmf.transform.ContentTransformer;
016: import com.uwyn.rife.engine.ElementSupport;
017: import java.util.Collection;
018:
019: /**
020: * A <code>ContentStore</code> stores the actual content data and is
021: * responsible for managing it.
022: * <p>The store doesn't work with paths, but with content ids. Each id
023: * identifies a specific content instance at a certain location and with a
024: * certain version number.
025: * <p>Each store is only capable of storing content with certain mime types.
026: * The store is optimized for a certain kind of content and will maybe not be
027: * able to correctly handle other types.
028: *
029: * @author Geert Bevin (gbevin[remove] at uwyn dot com)i
030: * @version $Revision: 3634 $
031: * @since 1.0
032: */
033: public interface ContentStore {
034: /**
035: * Installs a content store.
036: *
037: * @return <code>true</code> if the installation was successful; or
038: * <p><code>false</code> if it wasn't.
039: * @exception ContentManagerException if an unexpected error occurred
040: * @since 1.0
041: */
042: public boolean install() throws ContentManagerException;
043:
044: /**
045: * Removes a content store.
046: *
047: * @return <code>true</code> if the removal was successful; or
048: * <p><code>false</code> if it wasn't.
049: * @exception ContentManagerException if an unexpected error occurred
050: * @since 1.0
051: */
052: public boolean remove() throws ContentManagerException;
053:
054: /**
055: * Returns the collection of mime types that the content store supports.
056: *
057: * @return the collection of supported mime types
058: * @since 1.0
059: */
060: public Collection<MimeType> getSupportedMimeTypes();
061:
062: /**
063: * Generates the HTTP content type that corresponds best to the
064: * information in the provided <code>ContentInfo</code>.
065: *
066: * @param contentInfo the content info instance for which the content type
067: * has to be generated
068: * @return the generated content type
069: * @since 1.0
070: */
071: public String getContentType(ContentInfo contentInfo);
072:
073: /**
074: * Returns a <code>Formatter</code> instance that will be used to load and
075: * to format the content data.
076: *
077: * @param mimeType the mime type for which the formatter will be returned
078: * @param fragment <code>true</code> if the content that has to be
079: * formatter is a fragment; or
080: * <p><code>false</code> otherwise
081: * @return the corresponding formatter
082: * @since 1.0
083: */
084: public Formatter getFormatter(MimeType mimeType, boolean fragment);
085:
086: /**
087: * Stores the content data for a certain content id.
088: *
089: * @param id the id of the content whose data will be stored
090: * @param content the content whose data has to be stored
091: * @param transformer a transformer that will modify the content data; or
092: * <p><code>null</code> if the content data should stay intact
093: * @return <code>true</code> if the storing was successfully; or
094: * <p><code>false</code> if it wasn't.
095: * @exception ContentManagerException if an unexpected error occurred
096: * @since 1.0
097: */
098: public boolean storeContentData(int id, Content content,
099: ContentTransformer transformer)
100: throws ContentManagerException;
101:
102: /**
103: * Deletes the content data for a certain content id.
104: *
105: * @param id the id of the content whose data will be deleted
106: * @return <code>true</code> if the deletion was successfully; or
107: * <p><code>false</code> if it wasn't.
108: * @exception ContentManagerException if an unexpected error occurred
109: * @since 1.0
110: */
111: public boolean deleteContentData(int id)
112: throws ContentManagerException;
113:
114: /**
115: * Use the data of a certain content id.
116: * <p>Some content data will only be available during this method call due
117: * to their volatile nature (certain streams for instance). Therefore, one
118: * has to be careful when trying to move the data that is provided to the
119: * content user outside this method. The behaviour is undefined.
120: *
121: * @param id the id of the content whose data will be used
122: * @param user the content user instance that will be called to use
123: * content data
124: * @return the data that the {@link ContentDataUser#useContentData(Object)}
125: * returns after its usage
126: * @exception ContentManagerException if an unexpected error occurred
127: * @since 1.0
128: */
129: public <ResultType> ResultType useContentData(int id,
130: ContentDataUser user) throws ContentManagerException;
131:
132: /**
133: * Checks whether content data is available for a certain content id.
134: *
135: * @param id the id of the content whose data availability will be checked
136: * @return <code>true</code> if content data is available; or
137: * <p><code>false</code> if it isn't.
138: * @exception ContentManagerException if an expected error occurred
139: * @since 1.0
140: */
141: public boolean hasContentData(int id)
142: throws ContentManagerException;
143:
144: /**
145: * Retrieves the size of the content data for a certain content id.
146: * <p>Note that the result is specific to the data store. For instance,
147: * text data could return the number of characters, while image data could
148: * return the number of bytes.
149: *
150: * @param id the id of the content whose data size will be returned
151: * @return <code>-1</code> if no data is available for the provided
152: * content id; or
153: * <p>the requested content data size.
154: * @exception ContentManagerException if an unexpected error occurred
155: * @since 1.0
156: */
157: public int getSize(int id) throws ContentManagerException;
158:
159: /**
160: * Serves content data for a certain content id through the provided
161: * element.
162: * <p>This is intended to take over the complete handling of the request,
163: * so no other content should be output and no headers manipulated in the
164: * element if this method is called.
165: *
166: * @param element an active element instance
167: * @param id the id of the content whose data will be served
168: * @exception ContentManagerException if an unexpected error occurred
169: * @since 1.0
170: */
171: public void serveContentData(ElementSupport element, int id)
172: throws ContentManagerException;
173:
174: /**
175: * Retrieves a content data representation for use in html.
176: * <p>This is mainly used to integrate content data inside a html
177: * document. For instance, html content will be displayed as-is, while
178: * image content will cause an image tag to be generated with the correct
179: * source URL to serve the image.
180: *
181: * @param id the id of the content whose data will be displayed
182: * @param info the content info instance for which the html content
183: * has to be generated
184: * @param element an active element instance
185: * @param serveContentExitName the exit namet that leads to a {@link
186: * com.uwyn.rife.cmf.elements.ServeContent ServeContent} element. This will
187: * be used to generate URLs for content that can't be directly displayed
188: * in-line.
189: * @return the html content representation
190: * @exception ContentManagerException if an unexpected error occurred
191: * @since 1.0
192: */
193: public String getContentForHtml(int id, ContentInfo info,
194: ElementSupport element, String serveContentExitName)
195: throws ContentManagerException;
196: }
|