source/mir/media/MirMedia.java

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