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: ContentManager.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.dam.exceptions.ContentManagerException;
013: import com.uwyn.rife.cmf.transform.ContentTransformer;
014: import com.uwyn.rife.engine.ElementSupport;
015:
016: /**
017: * A <code>ContentManager</code> manages content that is stored in a back-end
018: * data store.
019: * <p>Content is isolated in repositories that should have unique names. The
020: * installation of a content manager creates an initial default repository. If
021: * others are needed, they have to be created explicitly.
022: * <p>All content is identified by a unique <code>location</code>. The
023: * location is formatted like this:
024: * <pre>repository:path</pre>
025: * <p>If the <code>repository:</code> prefix is omitted, the content will be
026: * stored in the default repository (see {@link
027: * com.uwyn.rife.cmf.ContentRepository#DEFAULT ContentRepository.DEFAULT}).
028: * <p>The path should start with a slash that makes it 'absolute', this is
029: * completely analogue to file system paths.
030: *
031: * @author Geert Bevin (gbevin[remove] at uwyn dot com)i
032: * @version $Revision: 3634 $
033: * @since 1.0
034: */
035: public interface ContentManager {
036: /**
037: * Installs a content manager.
038: *
039: * @return <code>true</code> if the installation was successful; or
040: * <p><code>false</code> if it wasn't.
041: * @exception ContentManagerException if an unexpected error occurred
042: * @since 1.0
043: */
044: public boolean install() throws ContentManagerException;
045:
046: /**
047: * Removes a content manager.
048: *
049: * @return <code>true</code> if the removal was successful; or
050: * <p><code>false</code> if it wasn't.
051: * @exception ContentManagerException if an unexpected error occurred
052: * @since 1.0
053: */
054: public boolean remove() throws ContentManagerException;
055:
056: /**
057: * Creates a new repository.
058: *
059: * @param name the name of the repository to create
060: * @return <code>true</code> if the creation was successful; or
061: * <p><code>false</code> if it wasn't.
062: * @exception ContentManagerException if an unexpected error occurred
063: * @since 1.0
064: */
065: public boolean createRepository(String name)
066: throws ContentManagerException;
067:
068: /**
069: * Checks if the content manager contains a certain repository.
070: *
071: * @param name the name of the repository to check
072: * @return <code>true</code> if the repository exists; or
073: * <p><code>false</code> if it doesn't.
074: * @exception ContentManagerException if an unexpected error occurred
075: * @since 1.4
076: */
077: public boolean containsRepository(String name)
078: throws ContentManagerException;
079:
080: /**
081: * Store content at a certain location.
082: * <p>If content is already present at this location, the new content will
083: * become the current version and the old content remains available as an
084: * older version.
085: *
086: * @param location the location where the content has to be stored.
087: * @param content the content that has to be stored
088: * @param transformer a transformer that will modify the content data; or
089: * <p><code>null</code> if the content data should stay intact
090: * @return <code>true</code> if the storing was successfully; or
091: * <p><code>false</code> if it wasn't.
092: * @exception ContentManagerException if an unexpected error occurred
093: * @since 1.0
094: */
095: public boolean storeContent(String location, Content content,
096: ContentTransformer transformer)
097: throws ContentManagerException;
098:
099: /**
100: * Delete the content at a certain location.
101: * <p>This will delete all versions of the content at that location.
102: *
103: * @param location the location where the content has to be deleted
104: * @return <code>true</code> if the deletion was successfully; or
105: * <p><code>false</code> if it wasn't.
106: * @exception ContentManagerException if an unexpected error occurred
107: * @since 1.0
108: */
109: public boolean deleteContent(String location)
110: throws ContentManagerException;
111:
112: /**
113: * Use the data of content at a certain location.
114: * <p>Some content data will only be available during this method call due
115: * to their volatile nature (certain streams for instance). Therefore, one
116: * has to be careful when trying to move the data that is provided to the
117: * content user outside this method. The behaviour is undefined.
118: *
119: * @param location the location whose content will be used
120: * @param user the content user instance that will be called to use
121: * content data
122: * @return the data that the {@link ContentDataUser#useContentData(Object)}
123: * returns after its usage
124: * @exception ContentManagerException if an unexpected error occurred
125: * @since 1.0
126: */
127: public <ResultType> ResultType useContentData(String location,
128: ContentDataUser user) throws ContentManagerException;
129:
130: /**
131: * Checks whether content data is available at a certain location.
132: *
133: * @param location the location that has to be checked
134: * @return <code>true</code> if content data is available; or
135: * <p><code>false</code> if it isn't.
136: * @exception ContentManagerException if an expected error occurred
137: * @since 1.0
138: */
139: public boolean hasContentData(String location)
140: throws ContentManagerException;
141:
142: /**
143: * Retrieves the content info from a certain location.
144: *
145: * @param location the location whose content info has to be retrieved
146: * @return an instance of <code>ContentInfo</code>; or
147: * <p><code>null</code> if no content is present at the location
148: * @exception ContentManagerException if an expected error occurred
149: * @since 1.0
150: */
151: public ContentInfo getContentInfo(String location)
152: throws ContentManagerException;
153:
154: /**
155: * Serves content data from a certain location through the provided
156: * element.
157: * <p>This is intended to take over the complete handling of the request,
158: * so no other content should be output and no headers manipulated in the
159: * element if this method is called.
160: *
161: * @param element an active element instance
162: * @param location the location whose content data has to be served
163: * @exception ContentManagerException if an expected error occurred
164: * @since 1.0
165: */
166: public void serveContentData(ElementSupport element, String location)
167: throws ContentManagerException;
168:
169: /**
170: * Retrieves a content representation for use in html.
171: * <p>This is mainly used to integrate content data inside a html
172: * document. For instance, html content will be displayed as-is, while
173: * image content will cause an image tag to be generated with the correct
174: * source URL to serve the image.
175: *
176: * @param location the location whose content will be displayed
177: * @param element an active element instance
178: * @param serveContentExitName the exit namet that leads to a {@link
179: * com.uwyn.rife.cmf.elements.ServeContent ServeContent} element. This will
180: * be used to generate URLs for content that can't be directly displayed
181: * in-line.
182: * @exception ContentManagerException if an expected error occurred
183: * @since 1.0
184: */
185: public String getContentForHtml(String location,
186: ElementSupport element, String serveContentExitName)
187: throws ContentManagerException;
188: }
|