svn commit: r1200288 - /sling/trunk/bundles/commons/mime/src/main/java/org/apache/sling/commons/mime/MimeTypeService.java

[fm...@apache.org]

Author: fmeschbe
Date: Thu Nov 10 12:21:30 2011
New Revision: 1200288

URL: http://svn.apache.org/viewvc?rev=1200288&view=rev
Log:
JavaDoc

Modified:
    sling/trunk/bundles/commons/mime/src/main/java/org/apache/sling/commons/mime/MimeTypeService.java

Modified: sling/trunk/bundles/commons/mime/src/main/java/org/apache/sling/commons/mime/MimeTypeService.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/commons/mime/src/main/java/org/apache/sling/commons/mime/MimeTypeService.java?rev=1200288&r1=1200287&r2=1200288&view=diff
==============================================================================
--- sling/trunk/bundles/commons/mime/src/main/java/org/apache/sling/commons/mime/MimeTypeService.java (original)
+++ sling/trunk/bundles/commons/mime/src/main/java/org/apache/sling/commons/mime/MimeTypeService.java Thu Nov 10 12:21:30 2011
@@ -20,7 +20,9 @@ import java.io.IOException;
 import java.io.InputStream;
 
 /**
- * The <code>MimeTypeService</code> TODO
+ * The <code>MimeTypeService</code> defines the service applications can call to
+ * resolve file names to MIME types and derive default file name extensions from
+ * MIME types.
  * <p>
  * This interface is not intended to be implemented by bundles. It is
  * implemented by this bundle and may be used by client bundles.
@@ -43,17 +45,17 @@ public interface MimeTypeService {
 
     /**
      * Returns the primary name extension to which the given
-     * <code>mimeType</code> maps. The returned extension must map to the
-     * given <code>mimeType</code> when fed to the
-     * {@link #getMimeType(String)} method. In other words, the expression
+     * <code>mimeType</code> maps. The returned extension must map to the given
+     * <code>mimeType</code> when fed to the {@link #getMimeType(String)}
+     * method. In other words, the expression
      * <code>mimeType.equals(getMimeType(getExtension(mimeType)))</code> must
      * always be <code>true</code> for any non-<code>null</code> MIME type.
      * <p>
      * A MIME type may be mapped to multiple extensions (e.g.
-     * <code>text/plain</code> to <code>txt</code>, <code>log</code>,
-     * ...). This method is expected to returned one of those extensions. It is
-     * up to the implementation to select an appropriate extension if multiple
-     * mappings exist for a single MIME type.
+     * <code>text/plain</code> to <code>txt</code>, <code>log</code>, ...). This
+     * method is expected to returned one of those extensions. It is up to the
+     * implementation to select an appropriate extension if multiple mappings
+     * exist for a single MIME type.
      *
      * @param mimeType The MIME type whose primary extension is requested.
      * @return A extension which maps to the given MIME type or
@@ -62,7 +64,35 @@ public interface MimeTypeService {
      */
     String getExtension(String mimeType);
 
+    /**
+     * Dynamically register a new mime type with one or more file name
+     * extensions. The first of those extensions is assumed to be default file
+     * name extension.
+     * <p>
+     * This registration is dynamic and not persisted.
+     *
+     * @param mimeType The MIME type to register
+     * @param extensions One or more file name extensions (without leading dot)
+     *            to register for the MIME type.
+     */
     void registerMimeType(String mimeType, String... extensions);
 
+    /**
+     * Register MIME types stored in the given input stream formatted as a
+     * regular MIME type file format: One entry per line. Each entry consists of
+     * two or more whitespace delimited fields where the first field is the MIME
+     * type and the rest of the fields are the file extensions. The first of the
+     * extensions is considered the default extension. Empty lines and lines
+     * starting with a hash sign (<code>#</code>) are ignored.
+     * <p>
+     * The stream is assumed to contain string data encoded with "ISO-8859-1".
+     * <p>
+     * This method reads the stream until an <code>IOException</code> occurs or
+     * until it has been fully read. The stream is not closed, though, by this
+     * method.
+     *
+     * @param mimeTabStream The stream to read the MIME type mappings from
+     * @throws IOException If an error occurs reading from the stream
+     */
     void registerMimeType(InputStream mimeTabStream) throws IOException;
 }