View Javadoc

1   /*
2    * Copyright 2005 Jukka Zitting <jz@yukatan.fi>
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package net.sf.exorcist.api;
17  
18  import java.io.IOException;
19  import java.io.InputStream;
20  import java.util.Collection;
21  
22  /***
23   * State of a content tree being migrated. The Exorcist system represents
24   * content as a combination of an XML document and a set of binary
25   * attachments. Instead of working on live content repositories, the Exorcist
26   * system uses exporter plugins to acquire state snapshots of selected parts of
27   * the content repositories. These snapshots are represented as ContentState
28   * instances that can then be modified or transformed by converter plugins
29   * without concerns for the originating content repository. Importer plugins
30   * use ContentState instances as content sources for populating or updating
31   * target content repositories.
32   * <p>
33   * The content XML document is kept in a serialized format to avoid forcing
34   * any specific XML document or processing model (DOM, SAX, etc.) on the
35   * Exorcist plugins. The downside of this feature is that each plugin needs
36   * to separately parse and serialize the content documents.
37   * <p>
38   * ContentState instances are normally created and managed by the Exorcist
39   * framework instead of individual plugins. It is up to the framework to
40   * decide whether to use a memory- or filesystem-based (or some other)
41   * ContentState implementation.
42   */
43  public interface ContentState {
44  
45      /***
46       * Sets the serialized XML document that represents the content
47       * state snapshot.
48       * <p>
49       * The given input stream should contain a well-formed XML document.
50       * The implementation class is not required to strictly enforce this
51       * requirement to avoid unnecessary processing, but failure to produce
52       * a well-formed XML document should still be considered a fatal error.  
53       * <p>
54       * The given input stream is consumed until it ends or an exception
55       * occurs, but it is not closed. It is the responsibility of the caller
56       * to properly close the stream. 
57       *
58       * @param content content XML stream
59       * @throws IOException if the stream can not be read
60       */
61      void setContent(InputStream content) throws IOException;
62  
63      /***
64       * Returns the serialized XML document that represents the content
65       * state snapshot.
66       * <p>
67       * The returned input stream should always contain a well-formed
68       * XML document although the implementation class might not strictly
69       * enforce this. Possible XML parsing exceptions can thus be treated
70       * as fatal errors.
71       * <p>
72       * The returned input stream belongs to the caller and should be closed
73       * when it is no longer used.
74       *
75       * @return content XML
76       * @throws IOException if the stream can not be created
77       */
78      InputStream getContent() throws IOException;
79  
80      /***
81       * Adds a binary attachment. The attachment is read from the given
82       * input stream and the SHA-1 hash of the received data is computed.
83       * The binary data is saved as a part of the content state and the
84       * identifying hash code is returned as a hex-encoded string.
85       * <p>
86       * The given input stream is consumed until it ends or an exception
87       * occurs, but it is not closed. It is the responsibility of the caller
88       * to properly close the stream. 
89       *
90       * @param data input stream containing the attachment
91       * @return the SHA-1 hash of the attachment
92       * @throws IOException if the attachment stream could not be read
93       */
94      String addAttachment(InputStream data) throws IOException;
95  
96      /***
97       * Returns the hashe codes of all the attachments.
98       *
99       * @return SHA-1 hashes of all the attachments
100      */
101     Collection getAttachmentHashes();
102 
103     /***
104      * Returns the attachment with the given hash code. The binary contents
105      * of the identified attachment is returned as an input stream. The caller
106      * should make sure that the returned input stream is properly closed when
107      * it is no longer used.
108      *
109      * @param hash SHA-1 hash of the attachment
110      * @return input stream containing the attached data
111      * @throws IllegalArgumentException if an attachment with the
112      *                                  given hash code does not exist
113      * @throws IOException if the stream can not be created
114      */
115     InputStream getAttachment(String hash)
116         throws IOException, IllegalArgumentException;
117 
118     /***
119      * Removes the attachment with the given hash code.
120      *
121      * @param hash SHA-1 hash of the attachment
122      * @throws IllegalArgumentException if an attachment with the
123      *                                  given hash code does not exist
124      */
125     void removeAttachment(String hash) throws IllegalArgumentException;
126 
127 }