source/mir/media/MediaHandler.java

   1 /*
   2  * Copyright (C) 2005 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  * You must obey the GNU General Public License in all respects for all of the code used
  23  * other than the above mentioned libraries.  If you modify this file, you may extend this
  24  * exception to your version of the file, but you are not obligated to do so.
  25  * If you do not wish to do so, delete this exception statement from your version.
  26  */
  27 package  mir.media;
  28
  29 import mir.entity.Entity;
  30 import mir.session.UploadedFile;
  31
  32 import java.io.InputStream;
  33
  34 /**
  35  * Interface for Media handling in Mir. All media handlers
  36  * must implement this interface. Each specific media type,
  37  * be it Gif, Jpeg, Mp3 audio, Real Audio or quicktime video
  38  * has special needs when it comes to representation on the various
  39  * pages (article, list, summary), must be stored differently and has a
  40  * different URL, etc... This interface allows Mir to support
  41  * an infinite (I hope) number of media types. Once this is done,
  42  * no code at any other level in Mir needs to be changed other than
  43  * adding the content-type <-> media handler name mapping in the
  44  * media_type table. The following is an example of the media_type
  45  * table:
  46  * <p>
  47  * id |  name   |        mime_type         | classname |   tablename   | dcname<br>
  48  *---+---------+--------------------------+-----------+---------------+-------<br>
  49  *  2 | unknown | application/octet-stream | --        | UploadedMedia | <br>
  50  *  3 | jpg     | image/gif                | ImagesGif | Images        | <br>
  51  *  4 | mp3     | audio/mp3                | Audio     | UploadedMedia | <br>
  52  * <p>
  53  * The "id" field is used as a mapping in the table that contains the media type
  54  * to the media_type table. For example, the images table has a to_media_type
  55  * field that contains the id in the media_type table.
  56  * <p>
  57  * The "name" field is used for various display/filenaming purposes. it should
  58  * match a valid file extension name for a media_type (we could have used the
  59  * content-type map for this....).
  60  * <p>
  61  * The "mime_type" field is the most important as it does maps the type to Java
  62  * classes (the database and media_handler name). We call those classes using
  63  * reflection. This way, once a Handler for a specific media type is implemented
  64  * and entered into the media_type table, no other Mir code needs to be modified.
  65  * <p>
  66  * The "classname" field is the name of the media handler (e.g MediaHandlerAudio)
  67  * we use it to call the MediaHandler methods via reflection.
  68  * <p>
  69  * The "tablename" is the name of the database database classes (e.g DatabaseImages
  70  * and EntityImages). We use this to fetch/database the media (meta)data in the db.
  71  * <p?
  72  * The "dcname" field is as of yet unused. Do search for "Dublin Core" on google
  73  * to learn more.
  74  * <p>
  75  * Most media handlers should just extend MediaHandlerGeneric (i.e inherit from
  76  * ) and just override the things that need to be specific. see MediaHandlerAudio
  77  *
  78  * @author <mh@nadir.org>, the Mir-coders group
  79  * @version $Id: MediaHandler.java,v 1.1.2.8 2005/12/24 11:43:36 zapata Exp $
  80  */
  81
  82 public interface MediaHandler {
  83   /**
  84    * Store the media content from an {@link UploadedFile}
  85    */
  86   public void store(UploadedFile anUploadedFile, Entity aMedia, Entity aMediaType) throws MediaExc, MediaFailure;
  87
  88   /**
  89    * Store the media content from an input stream.
  90    */
  91   public void store(InputStream anInputStream, Entity aMedia, Entity aMediaType) throws MediaExc, MediaFailure;
  92
  93   /**
  94    * Perform production related tasks for this media.
  95    */
  96   public void produce(Entity aMedia, Entity aMediaType ) throws MediaExc, MediaFailure;
  97
  98   /**
  99    * Get's the media data from database and returns it as an InputStream
 100    * Not very useful for most media types as they are stored in a file,
 101    * but very usefull for ones stored in the DB as it is necessary to get
 102    * it first before making a file out of it (in Producer*).
 103    */
 104   public InputStream getMedia (Entity aMedia, Entity aMediaType) throws MediaExc, MediaFailure;
 105
 106   /**
 107    * Pretty much like get() above. But get's the specific Icon
 108    * representation. useful for media stored in the DB.
 109    */
 110   public InputStream getThumbnail(Entity aMedia) throws MediaExc, MediaFailure;
 111
 112   /**
 113    * Returns the mime-type of the media's thumbnail
 114    */
 115   public String getThumbnailMimeType(Entity aMediaEntity, Entity aMediaType) throws MediaExc, MediaFailure;
 116
 117   /**
 118    * Returns the absolute filesystem path to where the media
 119    * content should be stored. This path is usually defined
 120    * in the configuration wich is accessible through the MirConfig
 121    * class.
 122    */
 123   public String getBaseStoragePath () throws MediaExc, MediaFailure;
 124
 125   /**
 126    * Returns the *relative* filesystem path to where the media
 127    * icon content should be stored. It is relative to the path
 128    * returned by getBaseStoragePath()
 129    * This path is usually defined
 130    * in the configuration wich is accessible through the MirConfig
 131    * class.
 132    */
 133   public String getBaseIconStoragePath () throws MediaExc, MediaFailure;
 134
 135   /**
 136    * Returns the base URL to that the media is accessible from
 137    * to the end user. This could be a URL to another host.
 138    * This is used in the Metadata stored in the DB and later on
 139    * ,the templates use it.
 140    * It is usually defined
 141    * in the configuration witch is accessible through the MirConfig
 142    * class.
 143    */
 144   public String getPublishHost () throws MediaExc, MediaFailure;
 145
 146   /**
 147    * Returns the file name of the Icon representing the media type.
 148    * It is used in the summary view.
 149    * It is usually defined
 150    * in the configuration wich is accessible through the MirConfig
 151    * class.
 152    */
 153   public String getBigIconName ();
 154
 155   /**
 156    * Returns the file name of the small Icon representing
 157    * the media type.
 158    * It is used in the right hand newswire list of the startpage.
 159    * It is usually defined
 160    * in the configuration wich is accessible through the MirConfig
 161    * class.
 162    */
 163   public String getTinyIconName ();
 164
 165   /**
 166    * Returns the IMG SRC "ALT" text to be used
 167    * for the Icon representations
 168    * @return String, the ALT text.
 169    */
 170   public String getIconAltName ();
 171
 172   /**
 173    * returns a brief text dscription of what this
 174    * media type is.
 175    * @return String
 176    */
 177   public String getDescr (Entity aMediaType);
 178
 179 }
 180
 181