X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=source%2Fmir%2Fmedia%2FMirMedia.java;h=7851d901f18f67fb4d05ddd793099f0a5b2ba59d;hb=bd509ef78e9f9fdf45915a2e98e8021882a6cfba;hp=736a06b3668de983620662e53e3989b949fc9ced;hpb=d0a53f777c4cd00509d4ab4a5b53893e42007212;p=mir.git diff --git a/source/mir/media/MirMedia.java b/source/mir/media/MirMedia.java index 736a06b3..7851d901 100755 --- a/source/mir/media/MirMedia.java +++ b/source/mir/media/MirMedia.java @@ -1,51 +1,238 @@ /* - * put your module comment here + * Copyright (C) 2001, 2002 The Mir-coders group + * + * This file is part of Mir. + * + * Mir is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * Mir is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Mir; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * + * In addition, as a special exception, The Mir-coders gives permission to link + * the code of this program with the com.oreilly.servlet library, any library + * licensed under the Apache Software License, The Sun (tm) Java Advanced + * Imaging library (JAI), The Sun JIMI library (or with modified versions of + * the above that use the same license as the above), and distribute linked + * combinations including the two. You must obey the GNU General Public + * License in all respects for all of the code used other than the above + * mentioned libraries. If you modify this file, you may extend this exception + * to your version of the file, but you are not obligated to do so. If you do + * not wish to do so, delete this exception statement from your version. */ - package mir.media; import java.util.*; +import java.io.InputStream; + +import freemarker.template.SimpleList; import mir.entity.*; /** - * Interfacedefinition für Datenbank-Adpatoren. Die Adaptoren legen - * jeweils das Verhalten und die Befehlsmächtigkeit der Datenbank - * fest. - * - * @author + * Interface for Media handling in Mir. All media handlers + * must implement this interface. Each specific media type, + * be it Gif, Jpeg, Mp3 audio, Real Audio or quicktime video + * has special needs when it comes to representation on the various + * pages (article, list, summary), must be stored differently and has a + * different URL, etc... This interface allows Mir to support + * an infinite (I hope) number of media types. Once this is done, + * no code at any other level in Mir needs to be changed other than + * adding the content-type <-> media handler name mapping in the + * media_type table. The following is an example of the media_type + * table: + *

+ * id | name | mime_type | classname | tablename | dcname
+ *---+---------+--------------------------+-----------+---------------+-------
+ * 2 | unknown | application/octet-stream | -- | UploadedMedia |
+ * 3 | jpg | image/gif | ImagesGif | Images |
+ * 4 | mp3 | audio/mp3 | Audio | UploadedMedia |
+ *

+ * The "id" field is used as a mapping in the table that contains the media type + * to the media_type table. For example, the images table has a to_media_type + * field that contains the id in the media_type table. + *

+ * The "name" field is used for various display/filenaming purposes. it should + * match a valid file extension name for a media_type (we could have used the + * content-type map for this....). + *

+ * The "mime_type" field is the most important as it does maps the type to Java + * classes (the storage and media_handler name). We call those classes using + * reflection. This way, once a Handler for a specific media type is implemented + * and entered into the media_type table, no other Mir code needs to be modified. + *

+ * The "classname" field is the name of the media handler (e.g MediaHandlerAudio) + * we use it to call the MediaHandler methods via reflection. + *

+ * The "tablename" is the name of the database storage classes (e.g DatabaseImages + * and EntityImages). We use this to fetch/storage the media (meta)data in the db. + * + * Most media handlers should just extend MediaHandlerGeneric (i.e inherit from + * ) and just override the things that need to be specific. see MediaHandlerAudio + * + * @author mh * @version 24.09.2001 */ public interface MirMedia{ - /* Liefert den Namen der Adaptorklasse - * @return Adaptorklasse als String - */ - public abstract boolean set (byte[] uploadedData, Entity ent, Entity mediaTypeEnt ); + /** + * Takes the uploaded media data itself, along with the media Entity + * which contains the Media metadata plus the MediaType entity containing + * all the info for the specific media type itself. It's job is store the + * Media data (content) itself, this could be on the local filesystem, in the + * DB or even on a remote host. It then inserts the MetaData in the DB. + * @param InputStream, a stream of the uploaded data. + * @param ent, an Entity holding the media MetaData + * @param mediaType, an Entity holding the media_table entry + * @return boolean, success/fail + * @see mir.entity.Entity + */ + public abstract void set (InputStream in, Entity ent, + Entity mediaTypeEnt ) throws MirMediaException; + + public abstract void produce (Entity ent, Entity mediaTypeEnt ) + throws MirMediaException; + + /** + * Get's the media data from storage and returns it as an InputStream + * Not very useful for most media types as they are stored in a file, + * but very usefull for ones stored in the DB as it is necessary to get + * it first before making a file out of it (in Producer*). + * @param ent, an Entity holding the media MetaData + * @param mediaType, an Entity holding the media_table entry + * @return java.io.InputStream + * @see mir.entity.Entity + */ + public abstract InputStream getMedia (Entity ent, Entity mediaTypeEnt) + throws MirMediaException; + + /** + * Pretty much like get() above. But get's the specific Icon + * representation. useful for media stored in the DB. + * @param ent, an Entity holding the media MetaData + * @return java.io.InputStream + * @see mir.entity.Entity + */ + public abstract InputStream getIcon (Entity ent) throws MirMediaException; + /** + * gets the final content representation for the media + * in the form of a URL (String) that allows someone to + * download, look at or listen to the media. (HREF, img src + * streaming link, etc..) + * It should use the helper functions in the StringUtil class to + * build URL's safely, eliminating any *illegal* user input. + * @param ent, an Entity holding the media MetaData + * @param mediaTypeEnt, an Entity holding the media_table entry + * @return String, the url. + * @see mir.entity.Entity + * @see mir.misc.StringUtil + */ + public abstract SimpleList getURL (Entity ent, Entity mediaTypeEnt) + throws MirMediaException; - public abstract byte[] get (Entity ent, Entity mediaTypeEnt); + /** + * Returns the absolute filesystem path to where the media + * content should be stored. This path is usually defined + * in the configuration wich is accessible through the MirConfig + * class. + * @return String, the path. + * @see mir.misc.MirConfig + */ + public abstract String getStoragePath () throws MirMediaException; + /** + * Returns the *relative* filesystem path to where the media + * icon content should be stored. It is relative to the path + * returned by getStoragePath() + * This path is usually defined + * in the configuration wich is accessible through the MirConfig + * class. + * @return String, the path. + * @see mir.misc.MirConfig + */ + public abstract String getIconStoragePath () throws MirMediaException; /** - * Liefert die URL für JDBC zurück, in den die Parameter user, pass und host - * eingefügt werden. Die URL wird aus der Konfiguration geholt. - * - * @param user user als String - * @param pass passwort als String - * @param host host als String - * @return url als String - */ - //public abstract String makeURL (Entity ent); + * Returns the base URL to that the media is accessible from + * to the end user. This could be a URL to another host. + * This is used in the Metadata stored in the DB and later on + * ,the templates use it. + * It is usually defined + * in the configuration witch is accessible through the MirConfig + * class. + * @return String, the base URL to the host. + * @see mir.misc.MirConfig + */ + public abstract String getPublishHost () throws MirMediaException; + /** + * Returns the file name of the Icon representing the media type. + * It is used in the summary view. + * It is usually defined + * in the configuration wich is accessible through the MirConfig + * class. + * @return String, the icon filename. + * @see mir.misc.MirConfig + */ + public abstract String getBigIconName (); + + /** + * Returns the file name of the small Icon representing + * the media type. + * It is used in the right hand newswire list of the startpage. + * It is usually defined + * in the configuration wich is accessible through the MirConfig + * class. + * @return String, the icon filename. + * @see mir.misc.MirConfig + */ + public abstract String getTinyIconName (); + + /** + * Returns the IMG SRC "ALT" text to be used + * for the Icon representations + * @return String, the ALT text. + */ + public abstract String getIconAltName (); + + /** + * your can all figure it out. + * @return boolean. + */ + public abstract boolean isVideo (); + + /** + * you can all figure it out. + * @return boolean. + */ + public abstract boolean isAudio (); /** - * Gibt zurück, ob das SQL der Datenbank den limit-Befehl beherrscht. - * @return true wenn ja, sonst false - */ - public abstract byte[] getIcon (Entity ent); + * you can all figure it out. + * @return boolean. + */ + public abstract boolean isImage (); + + /** + * returns a brief text dscription of what this + * media type is. + * @return String + */ + public abstract String getDescr (Entity mediaTypeEnt); }