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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags