001    package org.apache.fulcrum.mimetype;
002    
003    
004    /*
005     * Licensed to the Apache Software Foundation (ASF) under one
006     * or more contributor license agreements.  See the NOTICE file
007     * distributed with this work for additional information
008     * regarding copyright ownership.  The ASF licenses this file
009     * to you under the Apache License, Version 2.0 (the
010     * "License"); you may not use this file except in compliance
011     * with the License.  You may obtain a copy of the License at
012     *
013     *   http://www.apache.org/licenses/LICENSE-2.0
014     *
015     * Unless required by applicable law or agreed to in writing,
016     * software distributed under the License is distributed on an
017     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018     * KIND, either express or implied.  See the License for the
019     * specific language governing permissions and limitations
020     * under the License.
021     */
022    
023    
024    import java.io.File;
025    import java.util.Locale;
026    
027    import org.apache.fulcrum.mimetype.util.MimeType;
028    
029    /**
030     * The MimeType Service maintains mappings between MIME types and
031     * the corresponding file name extensions, and between locales and
032     * character encodings. The mappings are typically defined in
033     * properties or files located in user's home directory, Java home
034     * directory or the current class jar depending on the implementation.
035     *
036     * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
037     * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
038     * @version $Id: MimeTypeService.java 535465 2007-05-05 06:58:06Z tv $
039     */
040    public interface MimeTypeService
041    {
042        /** Avalon role - used to id the component within the manager */
043        String ROLE = MimeTypeService.class.getName();
044    
045        /**
046         * Sets a MIME content type mapping to extensions to the map.
047         * The extension is specified by a MIME type name followed
048         * by a list of file name extensions separated by a whitespace.
049         *
050         * @param spec a MIME type extension specification to add.
051         */
052        public void setContentType(String spec);
053    
054        /**
055         * Gets the MIME content type for a file as a string.
056         *
057         * @param file The file to look up a MIME type mapping for.
058         * @return the MIME type string.
059         */
060        public String getContentType(File file);
061    
062        /**
063         * Gets the MIME content type for a named file as a string.
064         *
065         * @param fileName The name of the file to look up a MIME type
066         * mapping for.
067         * @return the MIME type string.
068         */
069        public String getContentType(String fileName);
070    
071        /**
072         * Gets the MIME content type for a file name extension as a string.
073         *
074         * @param fileName The name of the file to look up a MIME type
075         * mapping for.
076         * @param def The default MIME type to use if no mapping exists.
077         * @return the MIME type string.
078         */
079        public String getContentType(String fileName, String def);
080    
081        /**
082         * Gets the MIME content type for a file.
083         *
084         * @param file the file.
085         * @return the MIME type.
086         */
087        public MimeType getMimeContentType(File file);
088    
089        /**
090         * Gets the MIME content type for a named file.
091         *
092         * @param name the name of the file.
093         * @return the MIME type.
094         */
095        public MimeType getMimeContentType(String name);
096    
097        /**
098         * Gets the MIME content type for a file name extension.
099         *
100         * @param ext the file name extension.
101         * @param def the default type if none is found.
102         * @return the MIME type.
103         */
104        public MimeType getMimeContentType(String ext,
105                                           String def);
106    
107        /**
108         * Gets the default file name extension for a MIME type.
109         * Note that the mappers are called in the reverse order.
110         *
111         * @param type the MIME type as a string.
112         * @return the file name extension or null.
113         */
114        public String getDefaultExtension(String type);
115    
116        /**
117         * Gets the default file name extension for a MIME type.
118         * Note that the mappers are called in the reverse order.
119         *
120         * @param mime the MIME type.
121         * @return the file name extension or null.
122         */
123        public String getDefaultExtension(MimeType mime);
124    
125        /**
126         * Sets a locale-charset mapping.
127         *
128         * @param key the key for the charset.
129         * @param charset the corresponding charset.
130         */
131        public  void setCharSet(String key,
132                                String charset);
133    
134        /**
135         * Gets the charset for a locale. First a locale specific charset
136         * is searched for, then a country specific one and lastly a language
137         * specific one. If none is found, the default charset is returned.
138         *
139         * @param locale the locale.
140         * @return the charset.
141         */
142        public String getCharSet(Locale locale);
143    
144        /**
145         * Gets the charset for a locale with a variant. The search
146         * is performed in the following order:
147         * "lang"_"country"_"variant"="charset",
148         * _"counry"_"variant"="charset",
149         * "lang"__"variant"="charset",
150         * __"variant"="charset",
151         * "lang"_"country"="charset",
152         * _"country"="charset",
153         * "lang"="charset".
154         * If nothing of the above is found, the default charset is returned.
155         *
156         * @param locale the locale.
157         * @param variant a variant field.
158         * @return the charset.
159         */
160        public String getCharSet(Locale locale,
161                                 String variant);
162    
163        /**
164         * Gets the charset for a specified key.
165         *
166         * @param key the key for the charset.
167         * @return the found charset or the default one.
168         */
169        public String getCharSet(String key);
170    
171        /**
172         * Gets the charset for a specified key.
173         *
174         * @param key the key for the charset.
175         * @param def the default charset if none is found.
176         * @return the found charset or the given default.
177         */
178        public String getCharSet(String key,
179                                 String def);
180    }