2 * put your module comment here
11 import freemarker.template.SimpleList;
16 * Interface for Media handling in Mir. All media handlers
17 * must implement this interface. Each specific media type,
18 * be it Gif, Jpeg, Mp3 audio, Real Audio or quicktime video
19 * has special needs when it comes to representation on the various
20 * pages (article, list, summary), must be stored differently and has a
21 * different URL, etc... This interface allows Mir to support
22 * an infinite (I hope) number of media types. Once this is done,
23 * no code at any other level in Mir needs to be changed other than
24 * adding the content-type <-> media handler name mapping in the
25 * media_type table. The following is an example of the media_type
28 * id | name | mime_type | classname | tablename | dcname<br>
29 *---+---------+--------------------------+-----------+---------------+-------<br>
30 * 2 | unknown | application/octet-stream | -- | UploadedMedia | <br>
31 * 3 | jpg | image/gif | ImagesGif | Images | <br>
32 * 4 | mp3 | audio/mp3 | Audio | UploadedMedia | <br>
34 * The "id" field is used as a mapping in the table that contains the media type
35 * to the media_type table. For example, the images table has a to_media_type
36 * field that contains the id in the media_type table.
38 * The "name" field is used for various display/filenaming purposes. it should
39 * match a valid file extension name for a media_type (we could have used the
40 * content-type map for this....).
42 * The "mime_type" field is the most important as it does maps the type to Java
43 * classes (the storage and media_handler name). We call those classes using
44 * reflection. This way, once a Handler for a specific media type is implemented
45 * and entered into the media_type table, no other Mir code needs to be modified.
47 * The "classname" field is the name of the media handler (e.g MediaHandlerAudio)
48 * we use it to call the MediaHandler methods via reflection.
50 * The "tablename" is the name of the database storage classes (e.g DatabaseImages
51 * and EntityImages). We use this to fetch/storage the media (meta)data in the db.
53 * The "dcname" field is as of yet unused. Do search for "Dublin Core" on google
56 * Most media handlers should just extend MediaHandlerGeneric (i.e inherit from
57 * ) and just override the things that need to be specific. see MediaHandlerAudio
59 * @author mh <heckmann@hbe.ca>
63 public interface MirMedia{
66 * Takes the uploaded media data itself, along with the media Entity
67 * which contains the Media metadata plus the MediaType entity containing
68 * all the info for the specific media type itself. It's job is store the
69 * Media data (content) itself, this could be on the local filesystem, in the
70 * DB or even on a remote host. It then inserts the MetaData in the DB.
71 * @param uploadedData, a byte array containing the uploaded data.
72 * @param ent, an Entity holding the media MetaData
73 * @param mediaType, an Entity holding the media_table entry
74 * @return boolean, success/fail
75 * @see mir.entity.Entity
77 public abstract boolean set (byte[] uploadedData, Entity ent,
78 Entity mediaTypeEnt ) throws MirMediaException;
80 public abstract void produce (Entity ent, Entity mediaTypeEnt )
81 throws MirMediaException;
84 * Get's the media data from storage and returns it as a byte array
85 * Not very useful for most media types as they are stored in a file,
86 * but very usefull for ones stored in the DB as it is necessary to get
87 * it first before making a file out of it (in Producer*).
88 * @param ent, an Entity holding the media MetaData
89 * @param mediaType, an Entity holding the media_table entry
91 * @see mir.entity.Entity
93 public abstract byte[] get (Entity ent, Entity mediaTypeEnt)
94 throws MirMediaException;
97 * Pretty much like get() above. But get's the specific Icon
98 * representation. useful for media stored in the DB.
99 * @param ent, an Entity holding the media MetaData
101 * @see mir.entity.Entity
103 public abstract byte[] getIcon (Entity ent) throws MirMediaException;
106 * gets the final content representation for the media
107 * in the form of a URL (String) that allows someone to
108 * download, look at or listen to the media. (HREF, img src
109 * streaming link, etc..)
110 * It should use the helper functions in the StringUtil class to
111 * build URL's safely, eliminating any *illegal* user input.
112 * @param ent, an Entity holding the media MetaData
113 * @param mediaTypeEnt, an Entity holding the media_table entry
114 * @return String, the url.
115 * @see mir.entity.Entity
116 * @see mir.misc.StringUtil
118 public abstract SimpleList getURL (Entity ent, Entity mediaTypeEnt)
119 throws MirMediaException;
122 * gets the summary representation for the media
123 * in the form of a URL (String). Usually the URL points
124 * to some sort of an icon that previews what kind of
125 * media an article will contain.
126 * It should use the helper functions in the StringUtil class to
127 * build URL's safely, eliminating any *illegal* user input.
128 * @param ent, an Entity holding the media MetaData
129 * @param mediaTypeEnt, an Entity holding the media_table entry
130 * @return String, the url.
131 * @see mir.entity.Entity
132 * @see mir.misc.StringUtil
134 public abstract String getListView (Entity ent, Entity mediaTypeEnt)
135 throws MirMediaException;
138 * Returns the absolute filesystem path to where the media
139 * content should be stored. This path is usually defined
140 * in the configuration wich is accessible through the MirConfig
142 * @return String, the path.
143 * @see mir.misc.MirConfig
145 public abstract String getStoragePath () throws MirMediaException;
148 * Returns the *relative* filesystem path to where the media
149 * icon content should be stored. It is relative to the path
150 * returned by getStoragePath()
151 * This path is usually defined
152 * in the configuration wich is accessible through the MirConfig
154 * @return String, the path.
155 * @see mir.misc.MirConfig
157 public abstract String getIconStoragePath () throws MirMediaException;
160 * Returns the base URL to that the media is accessible from
161 * to the end user. This could be a URL to another host.
162 * This is used in the Metadata stored in the DB and later on
163 * ,the templates use it.
164 * It is usually defined
165 * in the configuration witch is accessible through the MirConfig
167 * @return String, the base URL to the host.
168 * @see mir.misc.MirConfig
170 public abstract String getPublishHost () throws MirMediaException;
173 * Returns the file name of the Icon representing the media type.
174 * It is used in the summary view.
175 * It is usually defined
176 * in the configuration wich is accessible through the MirConfig
178 * @return String, the icon filename.
179 * @see mir.misc.MirConfig
181 public abstract String getBigIcon ();
184 * Returns the file name of the small Icon representing
186 * It is used in the right hand newswire list of the startpage.
187 * It is usually defined
188 * in the configuration wich is accessible through the MirConfig
190 * @return String, the icon filename.
191 * @see mir.misc.MirConfig
193 public abstract String getTinyIcon ();
196 * Returns the IMG SRC "ALT" text to be used
197 * for the Icon representations
198 * @return String, the ALT text.
200 public abstract String getIconAlt ();
203 * your all smart enough to figure it out.
206 public abstract boolean isVideo ();
209 * your all smart enough to figure it out.
212 public abstract boolean isAudio ();
215 * your all smart enough to figure it out.
218 public abstract boolean isImage ();