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