KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > emb > MetaDataEntityLocal


1 /*
2  * JBoss, the OpenSource J2EE webOS
3  *
4  * Distributable under LGPL license. See terms of license at gnu.org.
5  */

6
7 package javax.emb;
8
9 import javax.ejb.EJBLocalObject;
10
11 /**
12  * This basic interface defines behavior common to all kinds of metadata
13  * objects that are persistent and can be altered. It also extends
14  * EJBLocalObject and therefore represents the local interface of a Metadata
15  * Entity EJB.
16  *
17  * <p>MetaDataEntity EJBs consist of the two basic alterable properties:
18  *
19  * <ul><li>The xml property models the XML content of a Meta Data Entity EJB.
20  * XML content may be implicitly processed for the creation of persistent
21  * indexing information to allow efficient content search. The default for this
22  * property is <code>null</code>.
23  *
24  * <li>The name property models a file name that is used as a default in case
25  * the xml content has to be exported to a file. The default value for this
26  * property is <code>null</code>.
27  *
28  * @version <tt>$Revision: 1.1 $</tt>
29  * @author <a HREF="mailto:ricardoarguello@users.sourceforge.net">Ricardo
30  * ArgŁello</a>
31  */

32 public interface MetaDataEntityLocal extends EJBLocalObject
33 {
34    /**
35     * Adds the given Metadata Entity EJB to the receiver's set of children. If
36     * the given MetaDataEntity EJB is already part of the receiver's list of
37     * children no action is performed.
38     *
39     * @param child
40     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
41     */

42    void addChild(MetaDataEntityLocal child) throws MediaException;
43
44    /**
45     * Adds the given Media Entity EJB to the receiver's set of associated Media
46     * Entity EJBs that are described by the receiver. If the given Media Entity
47     * EJB is already part of the receiver's list no action is performed.
48     *
49     * @param mediaEntity
50     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
51     */

52    void addMediaEntity(MediaEntityLocal mediaEntity) throws MediaException;
53
54    // This method is listed in the code snippet at page 55 in the
55
// Proposed Final Draft, but I can't find it's description.
56
// URL exportMedia(URL) throws MediaException;
57

58    /**
59     * Returns the receiver's children as an array of Media Entity EJBs. The
60     * array is empty if no children are related.
61     */

62    MetaDataEntityLocal[] getChildren() throws MediaException;
63
64    /**
65     * Returns a timestamp stating when the receiver's persistent state was last
66     * modified.
67     *
68     * @return @throws MediaException
69     */

70    long getLastModified() throws MediaException;
71
72    /**
73     * Returns the Media Entity EJBs associated with the receiver. The array is
74     * empty if no media entity EJBs are related.
75     *
76     * @return @throws MediaException
77     */

78    MediaEntityLocal[] getMediaEntities() throws MediaException;
79
80    /**
81     * This method locates all Media Entity EJBs associated with the receiver
82     * that have the specified media format. If the given recursion flag is
83     * true, the search is extended to all Media Entity EJBs that relate to the
84     * receiver or one of its recursive children.
85     *
86     * @return MediaEntityLocal array.
87     * @throws java.lang.NullPointerException if the media format passed is
88     * <code>null</code>.
89     */

90    MediaEntityLocal[] getMediaEntities(
91       MediaFormat mediaFormat,
92       boolean searchCildren)
93       throws MediaException;
94
95    /**
96     * This method locates all Media Entity EJBs associated with the receiver
97     * that have the given mime type. If the given recursion flag is <code>true</code>,
98     * the search is extended to all Media Entity EJBs that relate to the
99     * receiver or one of its recursive children.
100     *
101     * @return MediaEntityLocal array.
102     * @throws java.lang.NullPointerException if the mime type passed is <code>null</code>.
103     */

104    MediaEntityLocal[] getMediaEntities(String mimeType, boolean searchCildren)
105       throws MediaException;
106
107    /**
108     * Returns the receiver's non-unique name as a String. The name is used as a
109     * file name hint in case the metadata XML content is to be stored in a file
110     * system and therefore may only contain characters that are valid in file
111     * names. Also, it should contain a file extension that represents the
112     * receiver's format. Note that as opposed to media entity EJBs, the name
113     * property is not required to contain a file extension registered with the
114     * MediaFormatRegistry.
115     *
116     * @return name.
117     * @throws MediaException
118     */

119    String getName() throws MediaException;
120
121    /**
122     * Returns the succeeding version edition of the receiver, which allows
123     * querying and a history chain of metadata objects that represent the same
124     * thing. The value <code>null</code> is returned if no next version
125     * exists.
126     *
127     * @return media entity.
128     * @throws MediaException
129     */

130    MetaDataEntityLocal getNextVersion() throws MediaException;
131
132    /**
133     * Returns the receiver's parents as an array of Metadata Entity EJBs. The
134     * array is empty if no parents are related.
135     *
136     * @return MediaEntityLocal array.
137     * @throws MediaException
138     */

139    MetaDataEntityLocal[] getParents() throws MediaException;
140
141    /**
142     * Returns the previous version of the receiver, which allows querying a
143     * history of metadata objects that represent the same logical thing. The
144     * value <code>null</code> is returned if no previous version exists.
145     *
146     * @return media entity.
147     * @throws MediaException
148     */

149    MetaDataEntityLocal getPreviousVersion() throws MediaException;
150
151    /**
152     * This method returns the receiver's content as an XML string.
153     *
154     * @return content as an XML string.
155     * @throws javax.emb.ContentAccessException if the value passed is <code>null</code>.
156     */

157    String getXML() throws MediaException;
158
159    /**
160     * Removes the given Metadata Entity EJB from the receiver's set of
161     * children. If the given MetaDataEntity EJB is not part of the receiver's
162     * list of children, no action is performed.
163     *
164     * @param child
165     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
166     * @throws MediaException
167     */

168    void removeChild(MetaDataEntityLocal child) throws MediaException;
169
170    /**
171     * Removes the given Media Entity EJB from the receiver's set of associated
172     * Media Entity EJBs that are described by the receiver. If the given Media
173     * Entity EJB is not part of the receiver's list no action is performed.
174     *
175     * @param mediaEntity
176     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
177     * @throws MediaException
178     */

179    void removeMediaEntity(MediaEntityLocal mediaEntity) throws MediaException;
180
181    /**
182     * Sets the receiver's non-unique name as a String. The name is used as a
183     * file name hint in case the media content is to be stored or published in
184     * a file system and therefore may only contain characters that are valid in
185     * file names. Also, it should contain a file extension that represents the
186     * receiver's media format. Note that as opposed media entity EJBs the name
187     * property is not required to contain a file extension registered with the
188     * MediaFormatRegistry.
189     *
190     * @param name
191     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
192     * @throws MediaException
193     */

194    void setName(String name) throws MediaException;
195
196    /**
197     * Defines the given metadata entity to be the previous version of the
198     * receiver, which allows querying a history chain of metadata objects that
199     * represent the same logical thing. In return, the operation causes the
200     * receiver to be the given metadata entity's successor. Passing the value
201     * <code>null</code> causes the receiver not to have a predecessor
202     * anymore. The operation is only allowed if version chain integrity is
203     * preserved:
204     *
205     * <ul><li>If the given metadata entity EJB is the receiver itself: A
206     * javax.emb.VersionChainIntegrityException is thrown.</li>
207     *
208     * <li>If the given metadata entity EJB is already the previous version of
209     * the receiver: No action is performed.</li>
210     *
211     * <li>If the given metadata entity EJB is <code>null</code>: A
212     * javax.emb.VersionChainIntegrityException is thrown if the receiver has a
213     * successor.</li>
214     *
215     * <li>Otherwise: A javax.emb.VersionChainIntegrityException is thrown if
216     * the given metadata entity EJB has a successor, or if the receiver has a
217     * predecessor, a successor, or both.</li></ul>
218     *
219     * @param metadata
220     * @throws MediaException
221     */

222    void setPreviousVersion(MetaDataEntityLocal metadata) throws MediaException;
223
224    /**
225     * If the given XML content is well formed, it replaces the receiver's
226     * current metadata content. If the given validation flag is <code>true</code>,
227     * the content is additionally strictly validated before the operation is
228     * performed.
229     *
230     * @param xmlContent
231     * @param validate
232     * @throws java.lang.NullPointerException if the content passed is <code>null</code>.
233     * @throws javax.emb.MetaDataValidationException if the validate flag is
234     * <code>true</code> and the content validation fails.
235     * @throws javax.emb.MetaDataSyntaxException if the XML content is not well
236     * formed, regardless of the validate flag.
237     */

238    void setXML(String xmlContent, boolean validate) throws MediaException;
239 }
Popular Tags