JavaDoc
git-svn-id: https://svn.apache.org/repos/asf/sling/trunk@1200288 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/main/java/org/apache/sling/commons/mime/MimeTypeService.java b/src/main/java/org/apache/sling/commons/mime/MimeTypeService.java
index 1d17c53..773934e 100644
--- a/src/main/java/org/apache/sling/commons/mime/MimeTypeService.java
+++ b/src/main/java/org/apache/sling/commons/mime/MimeTypeService.java
@@ -20,7 +20,9 @@
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 @@
/**
* 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 @@
*/
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;
}
