001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.content;
028:
029: import com.sun.midp.content.RegistryImpl;
030:
031: /**
032: * A <tt>ContentHandler</tt> provides the details of a
033: * content handler registration.
034: *
035: * Each ContentHandler contains the ID, content types, suffixes,
036: * actions, and action names. It provides the ID,
037: * authority, and application name and version of the content handler.
038: * The values are set when the content handler is
039: * {@link Registry#register register}ed.
040: * ContentHandler instances are immutable and thread safe.
041: * Content handlers can only be changed by re-registering which
042: * returns a new ContentHandler instance.
043: * The registered content handlers can be queried using the query methods
044: * of {@link Registry}.
045: *
046: * <H3>Content Types</H3>
047: * <P>
048: * For the purposes of this API, content types are simple opaque
049: * strings that are NOT case-sensitive. All comparisons are performed
050: * using case-insensitive string comparisons.
051: * By convention, the {@link #UNIVERSAL_TYPE UNIVERSAL_TYPE}
052: * is used to indicate any type. A content
053: * handler that can support any type of content should include it as
054: * one of types when it is registered. Any application can get the list
055: * of universal handlers with a query for the <code>UNIVERSAL_TYPE</code>.
056: * Handlers with this type are only returned
057: * by <code>Registry.findHandler</code> or
058: * <code>Registry.forType</code> if the type requested
059: * is equal to <code>UNIVERSAL_TYPE</code>. </p>
060: * <p>
061: * The most common content types are MIME types.
062: * <A HREF="http://www.ietf.org/rfc/rfc2046.txt">RFC-2046</A>
063: * defines the
064: * Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types.
065: * It defines the general structure of the MIME media typing system and
066: * defines an initial set of media types.
067: * <A HREF="http://www.ietf.org/rfc/rfc2046.txt">RFC-2048</A>
068: * describes the specific IANA registration procedures for
069: * MIME-related facilities.
070: * Other strings may be used as content types, but only if the type
071: * system semantics are well defined. An example of where the type system
072: * semantics are well defined is in the XML
073: * messaging schema.</P>
074: *
075: * <h3>Suffixes</h3>
076: * <P>
077: * A content handler can declare a set of suffixes that identify
078: * content it can handle based on the syntax of a URL.
079: * The suffix is a case-insensitive string that
080: * includes punctuation, for example ".png".
081: * For some URLs and content storage mechanisms, such as
082: * file systems, the content type is not readily available.
083: * To accommodate this,
084: * a mapping can be used to associate URL suffixes with content
085: * handlers. The common practice in file systems is to map filename
086: * extensions to content types. For example, a file ending in
087: * <code>.png</code>
088: * can be identified as content type <code>image/png</code>. This
089: * mapping is used if the content access mechanism does not support
090: * content typing or if the content type is not available from
091: * the content.
092: * For the <code>http</code>
093: * protocol, that supports a mechanism to identify the content type,
094: * the suffix matching MUST be used to identify content handlers if
095: * the type is not defined for a particular URL.
096: * <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396 -
097: * Uniform Resource Identifiers (URI): Generic Syntax</a>
098: * describes the syntax of URI's and the path component.
099: * Suffix matching consists of comparing each of the registered
100: * suffixes with the last n characters of the path component of the URL,
101: * where n is the length of the suffix.
102: * The comparison is case-insensitive and is done using the equivalent of
103: * <code>java.lang.String.regionMatches</code>.
104: * If multiple suffixes would match, the longest suffix that
105: * matches is used.
106: * </P>
107: *
108: * <h3>Actions</h3>
109: * <P>Each content handler registers a set of actions
110: * it supports.
111: * Actions are Java strings representing semantic functions the
112: * content handler can perform on every content type and suffix
113: * registered.
114: * Actions are case-sensitive strings.
115: * The set of actions is extensible but applications should
116: * choose from the following actions when appropriate:
117: * {@link ContentHandler#ACTION_OPEN open},
118: * {@link ContentHandler#ACTION_EDIT edit},
119: * {@link ContentHandler#ACTION_NEW new},
120: * {@link ContentHandler#ACTION_SEND send},
121: * {@link ContentHandler#ACTION_SAVE save},
122: * {@link ContentHandler#ACTION_EXECUTE execute},
123: * {@link ContentHandler#ACTION_SELECT select},
124: * {@link ContentHandler#ACTION_INSTALL install},
125: * {@link ContentHandler#ACTION_PRINT print}, and
126: * {@link ContentHandler#ACTION_STOP stop}.
127: *
128: * <P>The content handler application should provide localized action
129: * names for each action.
130: * The action names are used by applications that need to present the
131: * possible actions to users in locale appropriate terminology.
132: * A mapping for each action to action name should be created
133: * for each locale using the
134: * {@link ActionNameMap#ActionNameMap ActionNameMap.ActionNameMap} method.
135: * The action name maps for all the locales supported by the
136: * content handler MUST be included when the content handler is
137: * registered.
138: * The attribute <code>Microedition-Handler-<n>-<locale></code>
139: * is used to declare action names in the application packaging.
140: *
141: * <h3>Locale Strings</h3>
142: * <p>A locale string MUST include a language code,
143: * and may include a country code and a variant.
144: * The values are separated by a delimiter defined by the Java
145: * runtime environment.
146: * For MIDP, locale strings follow the definition of the
147: * system property <code>microedition.locale</code> and
148: * the delimiter MUST be a hyphen ("-" = U+002D).
149: * The values for the language, country code and variant are not
150: * validated.
151: * <p> Application developers should refer to
152: * ISO-639-1 for language codes and to ISO-3166-1 for country codes.
153: */
154: public interface ContentHandler {
155: /**
156: * Gets the content handler application ID.
157: * The ID uniquely identifies the content handler with
158: * the value provided to the {@link Registry#register register}
159: * method, if one was supplied, otherwise a unique ID.
160: *
161: * This information has been authenticated only if
162: * <code>getAuthority</code> is non-null.
163: *
164: * @return the ID; MUST NOT be <code>null</code>
165: */
166: public String getID();
167:
168: /**
169: * Gets the type supported by the content handler at the specified
170: * index.
171: * The type returned for each index must be the equal to the type
172: * at the same index in the <tt>types</tt> array passed to
173: * {@link Registry#register Registry.register}.
174: *
175: * @param index the index of the type
176: * @return the type at the specified index
177: * @exception IndexOutOfBoundsException if index is less than zero or
178: * greater than or equal to the value of the
179: * {@link #getTypeCount getTypeCount} method.
180: */
181: public String getType(int index);
182:
183: /**
184: * Gets the number of types supported by the content handler.
185: * The number of types must be equal to the length of the array
186: * of types passed to {@link Registry#register Registry.register}.
187: *
188: * @return the number of types
189: */
190: public int getTypeCount();
191:
192: /**
193: * Determines if a type is supported by the content handler.
194: *
195: * @param type the type to check for
196: * @return <code>true</code> if the type is supported;
197: * <code>false</code> otherwise
198: * @exception NullPointerException if <code>type</code>
199: * is <code>null</code>
200: */
201: public boolean hasType(String type);
202:
203: /**
204: * Gets the suffix supported by the content handler at the
205: * specified index.
206: * The suffix returned for each index must be the equal to the suffix
207: * at the same index in the <tt>suffixes</tt> array passed to
208: * {@link Registry#register Registry.register}.
209: *
210: * @param index the index of the suffix
211: * @return the suffix at the specified index
212: * @exception IndexOutOfBoundsException if index is less than zero or
213: * greater than or equal to the value of the
214: * {@link #getSuffixCount} method.
215: */
216: public String getSuffix(int index);
217:
218: /**
219: * Gets the number of suffixes supported by the content handler.
220: * The number of suffixes must be equal to the length of the array
221: * of suffixes passed to {@link Registry#register Registry.register}.
222: *
223: * @return the number of suffixes
224: */
225: public int getSuffixCount();
226:
227: /**
228: * Determines if a suffix is supported by the content handler.
229: *
230: * @param suffix the suffix to check for
231: * @return <code>true</code> if the suffix is supported;
232: * <code>false</code> otherwise
233: * @exception NullPointerException if <code>suffix</code>
234: * is <code>null</code>
235: */
236: public boolean hasSuffix(String suffix);
237:
238: /**
239: * Gets the action supported by the content handler at the
240: * specified index.
241: * The action returned for each index must be the equal to the action
242: * at the same index in the <tt>actions</tt> array passed to
243: * {@link Registry#register Registry.register}.
244: *
245: * @param index the index of the action
246: * @return the action at the specified index
247: * @exception IndexOutOfBoundsException if index is less than zero or
248: * greater than or equal to the value of the
249: * {@link #getActionCount getActionCount} method.
250: */
251: public String getAction(int index);
252:
253: /**
254: * Gets the number of actions supported by the content handler.
255: * The number of actions must be equal to the length of the array
256: * of actions passed to {@link Registry#register Registry.register}.
257: *
258: * @return the number of actions
259: */
260: public int getActionCount();
261:
262: /**
263: * Determines if an action is supported by the content handler.
264: *
265: * @param action the action to check for
266: * @return <code>true</code> if the action is supported;
267: * <code>false</code> otherwise
268: * @exception NullPointerException if <code>action</code>
269: * is <code>null</code>
270: */
271: public boolean hasAction(String action);
272:
273: /**
274: * Gets the mapping of actions to action names for the current
275: * locale supported by this content handler. The behavior is
276: * the same as invoking
277: * {@link #getActionNameMap getActionNameMap(String)}
278: * with the current locale.
279: *
280: * @return an ActionNameMap; if there is no map available for the
281: * current locale or if the locale is null or empty,
282: * then it MUST be <code>null</code>
283: */
284: public ActionNameMap getActionNameMap();
285:
286: /**
287: * Gets the mapping of actions to action names for the requested
288: * locale supported by this content handler.
289: * The locale is matched against the available ActionNameMaps.
290: * If a match is found it is used. If an exact match is
291: * not found, then the locale string is shortened and retried
292: * if a delimiter is present.
293: * For MIDP, the delimiter is ("-" = U+002D).
294: * The locale is shortened by retaining only the characters up to
295: * but not including the last occurrence of the delimiter.
296: *
297: * The shortening and matching is repeated as long as the string
298: * contains a delimiter.
299: * Effectively, this will try the full locale and then try
300: * without the variant and then without the country code,
301: * if present.
302: *
303: * @param locale for which to find an <tt>ActionNameMap</tt>;
304: * MUST NOT be <code>null</code>
305: * @return an <tt>ActionNameMap</tt>; if there is no map available for the
306: * locale, then it MUST be <code>null</code>
307: * @exception NullPointerException if the <code>locale</code>
308: * is <code>null</code>
309: */
310: public ActionNameMap getActionNameMap(String locale);
311:
312: /**
313: * Gets the number of action name maps supported by the content handler.
314: * The number of action name maps must be equal to the length of
315: * the array of action name maps passed to
316: * {@link Registry#register Registry.register}.
317: *
318: * @return the number of action name maps
319: */
320: public int getActionNameMapCount();
321:
322: /**
323: * Gets the ActionNameMap supported by the
324: * content handler at the specified index.
325: * The ActionNameMap returned for each index must be the equal
326: * to the ActionNameMap at the same index in the <tt>actionnames</tt>
327: * array passed to {@link Registry#register Registry.register}.
328: *
329: * @param index the index of the locale
330: * @return the ActionNameMap at the specified index
331: *
332: * @exception IndexOutOfBoundsException if index is less than zero or
333: * greater than or equal to the value of the
334: * {@link #getActionNameMapCount getActionNameMapCount} method.
335: */
336: public ActionNameMap getActionNameMap(int index);
337:
338: /**
339: * Gets the user-friendly application name of this content handler.
340: * The value is extracted from the normal installation information
341: * about the content handler application.
342: *
343: * @return the user-friendly name of the application;
344: * it MUST NOT be <code>null</code>
345: */
346: public String getAppName();
347:
348: /**
349: * Gets the version of this content handler.
350: * The value is extracted from the normal installation information
351: * about the content handler application.
352: * @return the version of the application;
353: * MAY be <code>null</code>
354: */
355: public String getVersion();
356:
357: /**
358: * Gets the authority that authenticated this application.
359: * This value MUST be <code>null</code> unless the device has been
360: * able to authenticate this application.
361: * If <code>non-null</code>, it is the string identifying the
362: * authority.
363: * The authority is determined by the security mechanisms
364: * and policy of the Java runtime environment.
365: * For signed MIDP applications, it is the subject of the signing
366: * certificate.
367: *
368: * @return the authority; may be <code>null</code>
369: */
370: public String getAuthority();
371:
372: /** Action to <code>open</code> content. */
373: public static final String ACTION_OPEN = "open";
374: /** Action to <code>edit</code> the content. */
375: public static final String ACTION_EDIT = "edit";
376: /** Action to <code>send</code> the content via email or messaging. */
377: public static final String ACTION_SEND = "send";
378: /** Action to <code>save</code> the content. */
379: public static final String ACTION_SAVE = "save";
380: /** Action to <code>execute</code> the content. */
381: public static final String ACTION_EXECUTE = "execute";
382: /**
383: * Action to <code>select</code> a value from the content,
384: * usually with user input, and return its value.
385: * For example, if the content were a URL of an address book,
386: * then the user would be asked to choose an entry or entries to
387: * return.
388: * The format of the return value depends on the content handler
389: * and the content, but if appropriate it should take the form
390: * of a URL.
391: */
392: public static final String ACTION_SELECT = "select";
393: /** Action to <code>install</code> the content on the device. */
394: public static final String ACTION_INSTALL = "install";
395: /** Action to <code>print</code> the content. */
396: public static final String ACTION_PRINT = "print";
397: /** Action to create <code>new</code> content. */
398: public static final String ACTION_NEW = "new";
399:
400: /**
401: * Action to request a content handler to stop processing
402: * the content identified by the URL, ID, and
403: * arguments. If stopping a previous request, these
404: * values should match the corresponding values in that request.
405: */
406: public final String ACTION_STOP = "stop";
407:
408: /**
409: * The universal type; a handler supporting this type can handle
410: * any type of content.
411: */
412: public static final String UNIVERSAL_TYPE = "*";
413: }
|