2 * Copyright (C) 2001, 2002 The Mir-coders group
4 * This file is part of Mir.
6 * Mir is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * Mir is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with Mir; if not, write to the Free Software
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 * In addition, as a special exception, The Mir-coders gives permission to link
21 * the code of this program with the com.oreilly.servlet library, any library
22 * licensed under the Apache Software License, The Sun (tm) Java Advanced
23 * Imaging library (JAI), The Sun JIMI library (or with modified versions of
24 * the above that use the same license as the above), and distribute linked
25 * combinations including the two. You must obey the GNU General Public
26 * License in all respects for all of the code used other than the above
27 * mentioned libraries. If you modify this file, you may extend this exception
28 * to your version of the file, but you are not obligated to do so. If you do
29 * not wish to do so, delete this exception statement from your version.
35 import java.io.InputStream;
37 import freemarker.template.SimpleList;
42 * Interface for Media handling in Mir. All media handlers
43 * must implement this interface. Each specific media type,
44 * be it Gif, Jpeg, Mp3 audio, Real Audio or quicktime video
45 * has special needs when it comes to representation on the various
46 * pages (article, list, summary), must be stored differently and has a
47 * different URL, etc... This interface allows Mir to support
48 * an infinite (I hope) number of media types. Once this is done,
49 * no code at any other level in Mir needs to be changed other than
50 * adding the content-type <-> media handler name mapping in the
51 * media_type table. The following is an example of the media_type
54 * id | name | mime_type | classname | tablename | dcname<br>
55 *---+---------+--------------------------+-----------+---------------+-------<br>
56 * 2 | unknown | application/octet-stream | -- | UploadedMedia | <br>
57 * 3 | jpg | image/gif | ImagesGif | Images | <br>
58 * 4 | mp3 | audio/mp3 | Audio | UploadedMedia | <br>
60 * The "id" field is used as a mapping in the table that contains the media type
61 * to the media_type table. For example, the images table has a to_media_type
62 * field that contains the id in the media_type table.
64 * The "name" field is used for various display/filenaming purposes. it should
65 * match a valid file extension name for a media_type (we could have used the
66 * content-type map for this....).
68 * The "mime_type" field is the most important as it does maps the type to Java
69 * classes (the storage and media_handler name). We call those classes using
70 * reflection. This way, once a Handler for a specific media type is implemented
71 * and entered into the media_type table, no other Mir code needs to be modified.
73 * The "classname" field is the name of the media handler (e.g MediaHandlerAudio)
74 * we use it to call the MediaHandler methods via reflection.
76 * The "tablename" is the name of the database storage classes (e.g DatabaseImages
77 * and EntityImages). We use this to fetch/storage the media (meta)data in the db.
79 * The "dcname" field is as of yet unused. Do search for "Dublin Core" on google
82 * Most media handlers should just extend MediaHandlerGeneric (i.e inherit from
83 * ) and just override the things that need to be specific. see MediaHandlerAudio
85 * @author mh <heckmann@hbe.ca>
89 public interface MirMedia{
92 * Takes the uploaded media data itself, along with the media Entity
93 * which contains the Media metadata plus the MediaType entity containing
94 * all the info for the specific media type itself. It's job is store the
95 * Media data (content) itself, this could be on the local filesystem, in the
96 * DB or even on a remote host. It then inserts the MetaData in the DB.
97 * @param InputStream, a stream of the uploaded data.
98 * @param ent, an Entity holding the media MetaData
99 * @param mediaType, an Entity holding the media_table entry
100 * @return boolean, success/fail
101 * @see mir.entity.Entity
103 public abstract void set (InputStream in, Entity ent,
104 Entity mediaTypeEnt ) throws MirMediaException;
106 public abstract void produce (Entity ent, Entity mediaTypeEnt )
107 throws MirMediaException;
110 * Get's the media data from storage and returns it as an InputStream
111 * Not very useful for most media types as they are stored in a file,
112 * but very usefull for ones stored in the DB as it is necessary to get
113 * it first before making a file out of it (in Producer*).
114 * @param ent, an Entity holding the media MetaData
115 * @param mediaType, an Entity holding the media_table entry
116 * @return java.io.InputStream
117 * @see mir.entity.Entity
119 public abstract InputStream getMedia (Entity ent, Entity mediaTypeEnt)
120 throws MirMediaException;
123 * Pretty much like get() above. But get's the specific Icon
124 * representation. useful for media stored in the DB.
125 * @param ent, an Entity holding the media MetaData
126 * @return java.io.InputStream
127 * @see mir.entity.Entity
129 public abstract InputStream getIcon (Entity ent) throws MirMediaException;
132 * gets the final content representation for the media
133 * in the form of a URL (String) that allows someone to
134 * download, look at or listen to the media. (HREF, img src
135 * streaming link, etc..)
136 * It should use the helper functions in the StringUtil class to
137 * build URL's safely, eliminating any *illegal* user input.
138 * @param ent, an Entity holding the media MetaData
139 * @param mediaTypeEnt, an Entity holding the media_table entry
140 * @return String, the url.
141 * @see mir.entity.Entity
142 * @see mir.misc.StringUtil
144 public abstract SimpleList getURL (Entity ent, Entity mediaTypeEnt)
145 throws MirMediaException;
148 * Returns the absolute filesystem path to where the media
149 * content should be stored. This path is usually defined
150 * in the configuration wich is accessible through the MirConfig
152 * @return String, the path.
153 * @see mir.misc.MirConfig
155 public abstract String getStoragePath () throws MirMediaException;
158 * Returns the *relative* filesystem path to where the media
159 * icon content should be stored. It is relative to the path
160 * returned by getStoragePath()
161 * This path is usually defined
162 * in the configuration wich is accessible through the MirConfig
164 * @return String, the path.
165 * @see mir.misc.MirConfig
167 public abstract String getIconStoragePath () throws MirMediaException;
170 * Returns the base URL to that the media is accessible from
171 * to the end user. This could be a URL to another host.
172 * This is used in the Metadata stored in the DB and later on
173 * ,the templates use it.
174 * It is usually defined
175 * in the configuration witch is accessible through the MirConfig
177 * @return String, the base URL to the host.
178 * @see mir.misc.MirConfig
180 public abstract String getPublishHost () throws MirMediaException;
183 * Returns the file name of the Icon representing the media type.
184 * It is used in the summary view.
185 * It is usually defined
186 * in the configuration wich is accessible through the MirConfig
188 * @return String, the icon filename.
189 * @see mir.misc.MirConfig
191 public abstract String getBigIconName ();
194 * Returns the file name of the small Icon representing
196 * It is used in the right hand newswire list of the startpage.
197 * It is usually defined
198 * in the configuration wich is accessible through the MirConfig
200 * @return String, the icon filename.
201 * @see mir.misc.MirConfig
203 public abstract String getTinyIconName ();
206 * Returns the IMG SRC "ALT" text to be used
207 * for the Icon representations
208 * @return String, the ALT text.
210 public abstract String getIconAltName ();
213 * your can all figure it out.
216 public abstract boolean isVideo ();
219 * you can all figure it out.
222 public abstract boolean isAudio ();
225 * you can all figure it out.
228 public abstract boolean isImage ();
231 * returns a brief text dscription of what this
235 public abstract String getDescr (Entity mediaTypeEnt);