some small changes delting unneeded imports. two new exceptions in mir.storage. usage...
[mir.git] / source / mir / media / MirMedia.java
1 /*
2  * Copyright (C) 2001, 2002  The Mir-coders group
3  *
4  * This file is part of Mir.
5  *
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.
10  *
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.
15  *
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
19  *
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.
30  */
31
32 package  mir.media;
33
34 import java.io.InputStream;
35
36 import mir.entity.Entity;
37 import freemarker.template.SimpleList;
38
39 /**
40  * Interface for Media handling in Mir. All media handlers
41  * must implement this interface. Each specific media type,
42  * be it Gif, Jpeg, Mp3 audio, Real Audio or quicktime video
43  * has special needs when it comes to representation on the various
44  * pages (article, list, summary), must be stored differently and has a 
45  * different URL, etc... This interface allows Mir to support 
46  * an infinite (I hope) number of media types. Once this is done,
47  * no code at any other level in Mir needs to be changed other than
48  * adding the content-type <-> media handler name mapping in the
49  * media_type table. The following is an example of the media_type
50  * table:
51  * <p>
52  * id |  name   |        mime_type         | classname |   tablename   | dcname<br>
53  *---+---------+--------------------------+-----------+---------------+-------<br>
54  *  2 | unknown | application/octet-stream | --        | UploadedMedia | <br>
55  *  3 | jpg     | image/gif                | ImagesGif | Images        | <br>
56  *  4 | mp3     | audio/mp3                | Audio     | UploadedMedia | <br>
57  * <p>
58  * The "id" field is used as a mapping in the table that contains the media type
59  * to the media_type table. For example, the images table has a to_media_type
60  * field that contains the id in the media_type table.
61  * <p>
62  * The "name" field is used for various display/filenaming purposes. it should
63  * match a valid file extension name for a media_type (we could have used the
64  * content-type map for this....). 
65  * <p>
66  * The "mime_type" field is the most important as it does maps the type to Java
67  * classes (the storage and media_handler name). We call those classes using
68  * reflection. This way, once a Handler for a specific media type is implemented
69  * and entered into the media_type table, no other Mir code needs to be modified.
70  * <p>
71  * The "classname" field is the name of the media handler (e.g MediaHandlerAudio)
72  * we use it to call the MediaHandler methods via reflection.
73  * <p>
74  * The "tablename" is the name of the database storage classes (e.g DatabaseImages
75  * and EntityImages). We use this to fetch/storage the media (meta)data in the db.
76  * <p?
77  * The "dcname" field is as of yet unused. Do search for "Dublin Core" on google
78  * to learn more.
79  * <p>
80  * Most media handlers should just extend MediaHandlerGeneric (i.e inherit from
81  * ) and just override the things that need to be specific. see MediaHandlerAudio
82  * 
83  * @author <mh@nadir.org>, the Mir-coders group
84  * @version $Id: MirMedia.java,v 1.15 2003/01/25 17:45:17 idfx Exp $
85  */
86
87 public interface  MirMedia{
88
89   /**
90    * Takes the uploaded media data itself, along with the media Entity
91    * which contains the Media metadata plus the MediaType entity containing
92    * all the info for the specific media type itself. It's job is store the
93    * Media data (content) itself, this could be on the local filesystem, in the
94    * DB or even on a remote host. It then inserts the MetaData in the DB.
95    * @param InputStream, a stream of the uploaded data.
96    * @param ent, an Entity holding the media MetaData
97    * @param mediaType, an Entity holding the media_table entry
98    * @return boolean, success/fail
99    * @see mir.entity.Entity
100    */
101   public abstract void set (InputStream in, Entity ent,
102                                 Entity mediaTypeEnt ) throws MirMediaException;
103
104         public abstract void produce (Entity ent, Entity mediaTypeEnt ) 
105     throws MirMediaException;
106
107   /**
108    * Get's the media data from storage and returns it as an InputStream
109    * Not very useful for most media types as they are stored in a file,
110    * but very usefull for ones stored in the DB as it is necessary to get
111    * it first before making a file out of it (in Producer*).
112    * @param ent, an Entity holding the media MetaData
113    * @param mediaType, an Entity holding the media_table entry
114    * @return java.io.InputStream
115    * @see mir.entity.Entity
116    */
117   public abstract InputStream getMedia (Entity ent, Entity mediaTypeEnt)
118           throws MirMediaException;
119
120   /**
121    * Pretty much like get() above. But get's the specific Icon
122    * representation. useful for media stored in the DB.
123    * @param ent, an Entity holding the media MetaData
124    * @return java.io.InputStream
125    * @see mir.entity.Entity
126    */
127   public abstract InputStream getIcon (Entity ent) throws MirMediaException;
128
129         /**
130    * gets the final content representation for the media
131    * in the form of a URL (String) that allows someone to 
132    * download, look at or listen to the media. (HREF, img src
133    * streaming link, etc..)
134    * It should use the helper functions in the StringUtil class to
135    * build URL's safely, eliminating any *illegal* user input.
136    * @param ent, an Entity holding the media MetaData
137    * @param mediaTypeEnt, an Entity holding the media_table entry
138    * @return String, the url.
139    * @see mir.entity.Entity
140    * @see mir.misc.StringUtil
141    */
142   public abstract SimpleList getURL (Entity ent, Entity mediaTypeEnt)
143     throws MirMediaException;
144
145         /**
146    * Returns the absolute filesystem path to where the media
147    * content should be stored. This path is usually defined
148    * in the configuration wich is accessible through the MirConfig
149    * class.
150    * @return String, the path.
151    * @see mir.misc.MirConfig
152    */
153   public abstract String getStoragePath () throws MirMediaException;
154
155         /**
156    * Returns the *relative* filesystem path to where the media
157    * icon content should be stored. It is relative to the path
158    * returned by getStoragePath()
159    * This path is usually defined
160    * in the configuration wich is accessible through the MirConfig
161    * class.
162    * @return String, the path.
163    * @see mir.misc.MirConfig
164    */
165   public abstract String getIconStoragePath () throws MirMediaException;
166
167         /**
168    * Returns the base URL to that the media is accessible from
169    * to the end user. This could be a URL to another host.
170    * This is used in the Metadata stored in the DB and later on
171    * ,the templates use it.
172    * It is usually defined
173    * in the configuration witch is accessible through the MirConfig
174    * class.
175    * @return String, the base URL to the host.
176    * @see mir.misc.MirConfig
177    */
178   public abstract String getPublishHost () throws MirMediaException;
179
180         /**
181    * Returns the file name of the Icon representing the media type.
182    * It is used in the summary view.
183    * It is usually defined
184    * in the configuration wich is accessible through the MirConfig
185    * class.
186    * @return String, the icon filename.
187    * @see mir.misc.MirConfig
188    */
189   public abstract String getBigIconName ();
190   
191         /**
192    * Returns the file name of the small Icon representing 
193    * the media type.
194    * It is used in the right hand newswire list of the startpage.
195    * It is usually defined
196    * in the configuration wich is accessible through the MirConfig
197    * class.
198    * @return String, the icon filename.
199    * @see mir.misc.MirConfig
200    */
201   public abstract String getTinyIconName ();
202
203         /**
204    * Returns the IMG SRC "ALT" text to be used
205    * for the Icon representations
206    * @return String, the ALT text.
207    */
208   public abstract String getIconAltName ();
209
210         /**
211    * your can all figure it out.
212    * @return boolean.
213    */
214   public abstract boolean isVideo ();
215
216         /**
217    * you can all figure it out.
218    * @return boolean.
219    */
220   public abstract boolean isAudio ();
221
222         /**
223    * you can all figure it out.
224    * @return boolean.
225    */
226   public abstract boolean isImage ();
227
228   /**
229    * returns a brief text dscription of what this
230    * media type is.
231    * @return String
232    */
233   public abstract String getDescr (Entity mediaTypeEnt);
234
235 }
236
237