1 /*
2 * Copyright 2007-2009 Medsea Business Solutions S.L.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package eu.medsea.mimeutil.handler;
17
18 import eu.medsea.mimeutil.TextMimeType;
19
20 /**
21 * This interface is to be implemented by all TextMmeDetector(s)
22 * that are registered with the TextMimeDetector
23 * <p>
24 * A scenario in which you would want to use this feature is when
25 * handling text files that are ultimately XML type files.
26 * </p>
27 * <p>
28 * These handlers are given a chance to influence the returned
29 * MimeType present in the Collection returned from the TextMimeDetector
30 * that is pre-registered with mime-util. Each TextMimeHandler will
31 * be called in the order they are registered. If the handle(...) method
32 * returns true, no more handlers will be called but if handle(...) returns false
33 * the next handler in the chain will be called and given a chance to change the
34 * information contained in the passed in TextMimeType such as the mediaType, subType
35 * and encoding.
36 * </p>
37 * <p>
38 * As these operate in a chain like fashion you can create generic handlers for say
39 * XML files that checks the content for the presence of the xml declaration and set
40 * the media and sub types of the MimeType to text/xml instead of the default text/plain.
41 * You can also change the encoding from the guessed encoding to the encoding defined
42 * in the XML file. The next handler could be configured to only execute it's logic
43 * if the sub type of the TextMimeType is or contains xml. This handler could then look to see if
44 * the content is actually and SVG file and change the media type to application, the sub type to svg+xml
45 * and return true from the handle method so that no more handlers in the chain are called because
46 * we now know we have the correct information.
47 * </p>
48 * <p>
49 * For some VERY basic implementations of TextMimeHandler(s) using string functions see the unit tests for
50 * the TextMimeDetector. For your implementations you will probably want to use regular expressions
51 * to determine content or even to decide if this handler is interested in the content.
52 * </p>
53 * <p>
54 * This is one area that you can contribute back to the community. If you have a first class TexMimeHandler
55 * implementation for a specific type of text file content then please consider donating it back to
56 * the project and we will release this in a future contributed library. You could even sell these as
57 * commercial add ons if it's the bees knees for a specific, hard to detect, type of text content.
58 * </p>
59 * @author Steven McArdle
60 *
61 */
62 public interface TextMimeHandler {
63 /**
64 * All TextMimeHandler(s) will have this method that has a chance
65 * to re-handle what the TextMimeDetector has decided
66 * @param mimeType what the current TextMimeType looks like i.e. it's
67 * current MimeType and encoding
68 * @param content is the actual text you can use to better determine what this text really is
69 * @return if true is returned then no more registered TextMimeHandler(s) will fire after this.
70 * false means that the next registered TextMimeHandler in the list gets a chance to also change
71 * the MimeType and encoding.
72 */
73 public boolean handle(final TextMimeType mimeType, final String content);
74 }