source/mir/media/MediaHandler.java

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