1 /*
2 * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.activation;
27
28 import java.util.Map;
29 import java.util.WeakHashMap;
30
31
32 /**
33 * The CommandMap class provides an interface to a registry of
34 * command objects available in the system.
35 * Developers are expected to either use the CommandMap
36 * implementation included with this package (MailcapCommandMap) or
37 * develop their own. Note that some of the methods in this class are
38 * abstract.
39 *
40 * @since 1.6
41 */
42 public abstract class CommandMap {
43 private static CommandMap defaultCommandMap = null;
44 private static Map<ClassLoader,CommandMap> map =
45 new WeakHashMap<ClassLoader,CommandMap>();
46
47 /**
48 * Get the default CommandMap.
49 * <p>
50 *
51 * <ul>
52 * <li> In cases where a CommandMap instance has been previously set
53 * to some value (via <i>setDefaultCommandMap</i>)
54 * return the CommandMap.
55 * <li>
56 * In cases where no CommandMap has been set, the CommandMap
57 * creates an instance of <code>MailcapCommandMap</code> and
58 * set that to the default, returning its value.
59 *
60 * </ul>
61 *
62 * @return the CommandMap
63 */
64 public static synchronized CommandMap getDefaultCommandMap() {
65 if (defaultCommandMap != null)
66 return defaultCommandMap;
67
68 // fetch per-thread-context-class-loader default
69 ClassLoader tccl = SecuritySupport.getContextClassLoader();
70 CommandMap def = map.get(tccl);
71 if (def == null) {
72 def = new MailcapCommandMap();
73 map.put(tccl, def);
74 }
75 return def;
76 }
77
78 /**
79 * Set the default CommandMap. Reset the CommandMap to the default by
80 * calling this method with <code>null</code>.
81 *
82 * @param commandMap The new default CommandMap.
83 * @exception SecurityException if the caller doesn't have permission
84 * to change the default
85 */
86 public static synchronized void setDefaultCommandMap(CommandMap commandMap) {
87 SecurityManager security = System.getSecurityManager();
88 if (security != null) {
89 try {
90 // if it's ok with the SecurityManager, it's ok with me...
91 security.checkSetFactory();
92 } catch (SecurityException ex) {
93 // otherwise, we also allow it if this code and the
94 // factory come from the same (non-system) class loader (e.g.,
95 // the JAF classes were loaded with the applet classes).
96 ClassLoader cl = CommandMap.class.getClassLoader();
97 if (cl == null || cl.getParent() == null ||
98 cl != commandMap.getClass().getClassLoader()) {
99 throw ex;
100 }
101 }
102 }
103 // remove any per-thread-context-class-loader CommandMap
104 map.remove(SecuritySupport.getContextClassLoader());
105 defaultCommandMap = commandMap;
106 }
107
108 /**
109 * Get the preferred command list from a MIME Type. The actual semantics
110 * are determined by the implementation of the CommandMap.
111 *
112 * @param mimeType the MIME type
113 * @return the CommandInfo classes that represent the command Beans.
114 */
115 abstract public CommandInfo[] getPreferredCommands(String mimeType);
116
117 /**
118 * Get the preferred command list from a MIME Type. The actual semantics
119 * are determined by the implementation of the CommandMap. <p>
120 *
121 * The <code>DataSource</code> provides extra information, such as
122 * the file name, that a CommandMap implementation may use to further
123 * refine the list of commands that are returned. The implementation
124 * in this class simply calls the <code>getPreferredCommands</code>
125 * method that ignores this argument.
126 *
127 * @param mimeType the MIME type
128 * @param ds a DataSource for the data
129 * @return the CommandInfo classes that represent the command Beans.
130 * @since 1.6, JAF 1.1
131 */
132 public CommandInfo[] getPreferredCommands(String mimeType, DataSource ds) {
133 return getPreferredCommands(mimeType);
134 }
135
136 /**
137 * Get all the available commands for this type. This method
138 * should return all the possible commands for this MIME type.
139 *
140 * @param mimeType the MIME type
141 * @return the CommandInfo objects representing all the commands.
142 */
143 abstract public CommandInfo[] getAllCommands(String mimeType);
144
145 /**
146 * Get all the available commands for this type. This method
147 * should return all the possible commands for this MIME type. <p>
148 *
149 * The <code>DataSource</code> provides extra information, such as
150 * the file name, that a CommandMap implementation may use to further
151 * refine the list of commands that are returned. The implementation
152 * in this class simply calls the <code>getAllCommands</code>
153 * method that ignores this argument.
154 *
155 * @param mimeType the MIME type
156 * @param ds a DataSource for the data
157 * @return the CommandInfo objects representing all the commands.
158 * @since 1.6, JAF 1.1
159 */
160 public CommandInfo[] getAllCommands(String mimeType, DataSource ds) {
161 return getAllCommands(mimeType);
162 }
163
164 /**
165 * Get the default command corresponding to the MIME type.
166 *
167 * @param mimeType the MIME type
168 * @param cmdName the command name
169 * @return the CommandInfo corresponding to the command.
170 */
171 abstract public CommandInfo getCommand(String mimeType, String cmdName);
172
173 /**
174 * Get the default command corresponding to the MIME type. <p>
175 *
176 * The <code>DataSource</code> provides extra information, such as
177 * the file name, that a CommandMap implementation may use to further
178 * refine the command that is chosen. The implementation
179 * in this class simply calls the <code>getCommand</code>
180 * method that ignores this argument.
181 *
182 * @param mimeType the MIME type
183 * @param cmdName the command name
184 * @param ds a DataSource for the data
185 * @return the CommandInfo corresponding to the command.
186 * @since 1.6, JAF 1.1
187 */
188 public CommandInfo getCommand(String mimeType, String cmdName,
189 DataSource ds) {
190 return getCommand(mimeType, cmdName);
191 }
192
193 /**
194 * Locate a DataContentHandler that corresponds to the MIME type.
195 * The mechanism and semantics for determining this are determined
196 * by the implementation of the particular CommandMap.
197 *
198 * @param mimeType the MIME type
199 * @return the DataContentHandler for the MIME type
200 */
201 abstract public DataContentHandler createDataContentHandler(String
202 mimeType);
203
204 /**
205 * Locate a DataContentHandler that corresponds to the MIME type.
206 * The mechanism and semantics for determining this are determined
207 * by the implementation of the particular CommandMap. <p>
208 *
209 * The <code>DataSource</code> provides extra information, such as
210 * the file name, that a CommandMap implementation may use to further
211 * refine the choice of DataContentHandler. The implementation
212 * in this class simply calls the <code>createDataContentHandler</code>
213 * method that ignores this argument.
214 *
215 * @param mimeType the MIME type
216 * @param ds a DataSource for the data
217 * @return the DataContentHandler for the MIME type
218 * @since 1.6, JAF 1.1
219 */
220 public DataContentHandler createDataContentHandler(String mimeType,
221 DataSource ds) {
222 return createDataContentHandler(mimeType);
223 }
224
225 /**
226 * Get all the MIME types known to this command map.
227 * If the command map doesn't support this operation,
228 * null is returned.
229 *
230 * @return array of MIME types as strings, or null if not supported
231 * @since 1.6, JAF 1.1
232 */
233 public String[] getMimeTypes() {
234 return null;
235 }
236 }