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