01: /*
02: * Copyright 2004 Outerthought bvba and Schaubroeck nv
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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 org.outerj.daisy.repository;
17:
18: import org.outerx.daisy.x10.PartDocument;
19:
20: import java.io.InputStream;
21:
22: /**
23: * Parts belong to documents (or versions of documents), and are the things
24: * that contain the actual data of the document.
25: *
26: * <p>A part is always associated with a {@link org.outerj.daisy.repository.schema.PartType}.
27: *
28: * <p>The repository itself does not really place any restrictions
29: * on the kind of data that can be contained in a part. However,
30: * parts whose part type's {@link org.outerj.daisy.repository.schema.PartType#isDaisyHtml()}
31: * method returns true should contain XML-well-formed HTML (not namespaced XHTML).
32: *
33: * <p>Note that a part has no setters methods, modifications can only
34: * be done through the containing {@link Document}. This is because
35: * parts can also be obtained from {@link Version}s, which are not
36: * modifiable.
37: */
38: public interface Part {
39: /**
40: * The id of the part type of this part. More information on the part type
41: * can then be retrieved from the {@link org.outerj.daisy.repository.schema.RepositorySchema}.
42: */
43: long getTypeId();
44:
45: /**
46: * Get the name of the part type.
47: */
48: String getTypeName();
49:
50: /**
51: * Get the mime-type of the data currently stored in this part.
52: */
53: String getMimeType();
54:
55: /**
56: * Get the file name for this part, can be null. The file name is a user-selected
57: * string used to store a proposed file name that can be used when downloading the
58: * data stored in this part into a file. It is not the name of the file that the
59: * repository uses to store the data (if this would be file-based, which isn't
60: * defined by this API).
61: */
62: String getFileName();
63:
64: /**
65: * Get the actual data stored in this part. The data is only retrieved
66: * when this method is called, and is not stored inside this object after
67: * retrieval.
68: */
69: byte[] getData() throws RepositoryException;
70:
71: /**
72: * Get the data stored in this part. The caller is, of course, responsible
73: * for closing the input stream in order to avoid resource leakage (thus
74: * always do this in a try-finally block).
75: */
76: InputStream getDataStream() throws RepositoryException;
77:
78: /**
79: * Get the size of the data. For new or modified parts, this will return -1
80: * until the document to which the part belongs is saved.
81: */
82: long getSize();
83:
84: /**
85: * Gets the ID of the last version in which the data of this part was changed.
86: * Note that this only applies to the binary data, not to the filename or mime type.
87: * If a part has been updated, but not yet saved, this method returns -1. For parts
88: * retrieved via a version, this will never be the case.
89: *
90: * @since Daisy 2.0.
91: */
92: long getDataChangedInVersion();
93:
94: /**
95: * Get an XML document describing this part.
96: */
97: PartDocument getXml();
98: }
|