| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML> |
| <HEAD> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <TITLE>Using content types</TITLE> |
| |
| <link rel="stylesheet" type="text/css" HREF="../book.css"> |
| </HEAD> |
| <BODY BGCOLOR="#ffffff"> |
| |
| <h2>Using content types</h2> |
| <blockquote><i> Note: For this discussion, we specifically avoid the use |
| of the word <b>file</b> when talking about content. The runtime content engine |
| does not assume that content is contained in a file in the file system. However, |
| it does include protocol that allows content types to be associated with file-naming |
| patterns. In practice, these file names represent files in the file system, |
| but nothing in the implementation of the content system assumes that the content |
| is located in the file system. <a HREF="resInt_content.htm">File encoding and |
| content types</a> discusses the file-oriented content type capabilities contributed |
| by the platform resources plug-in and is a must-read for developers interested |
| in using the content type API in that context.</i></blockquote> |
| <h3>Finding out about content types</h3> |
| <p>Content types are represented by <b><a href="../reference/api/org/eclipse/core/runtime/content/IContentType.html">IContentType</a></b>. |
| This interface represents a unique content type that knows how to read a data |
| stream and interpret content type-specific information. Content types are hierarchical |
| in nature. For example, a content type for XML data is considered a child of |
| the text content type. This allows new content types to leverage the attributes |
| or behavior of more general content types. </p> |
| <p>The <b><a href="../reference/api/org/eclipse/core/runtime/content/IContentTypeManager.html">IContentTypeManager</a></b> |
| is the entry point that gives access to most of the content type related API |
| provided by the platform runtime. To obtain a reference to the platform <b><a href="../reference/api/org/eclipse/core/runtime/content/IContentTypeManager.html">IContentTypeManager</a></b>, |
| clients can use the <b><a href="../reference/api/org/eclipse/core/runtime/Platform.html">Platform</a></b> |
| API:</p> |
| <pre>IContentTypeManager contentTypeManager = Platform.getContentTypeManager();</pre> |
| <p> Clients can use the platform <b><a href="../reference/api/org/eclipse/core/runtime/content/IContentTypeManager.html">IContentTypeManager</a></b> |
| to find out about the content types in the system. </p> |
| <ul> |
| <li><b>getAllContentTypes</b> allows clients to get all of the content types |
| defined in the platform. </li> |
| <li><b>getContentType</b> allows clients to obtain a content type by its unique |
| identifier.</li> |
| </ul> |
| <h3>Detecting the content type for a data stream</h3> |
| <p>Given a stream of bytes, it is possible to determine its content type by calling |
| the <b><a href="../reference/api/org/eclipse/core/runtime/content/IContentTypeManager.html">IContentTypeManager</a></b> |
| API as follows:</p> |
| <pre> |
| InputStream stream = ...; |
| IContentType contentType = contentTypeManager.findContentTypeFor(stream, "file.xml"); |
| stream.close(); |
| </pre> |
| <p>This will return the most appropriate <a href="../reference/api/org/eclipse/core/runtime/content/IContentType.html"><strong>IContentType</strong></a> |
| given the input provided, or <code>null</code> if none can be found. Multiple |
| content types might be deemed appropriate for a given data stream. In that case, |
| the platform uses some heuristics to determine which one should be selected. |
| The file name is the first criterion by which content types are selected. It |
| can be omitted, but this has two issues: the results might not be as correct |
| because many unrelated content types might accept the same input; there is also |
| a big performance hit, since all content types in the platform have to be given |
| a chance of analysing the stream. So, unless it is not available, clients should |
| always provide a file name along with the stream.</p> |
| <h3>Describing a data stream</h3> |
| <p>Another interesting feature of the content type support in the platform is |
| the ability of <em>describing the contents</em> of a binary or character stream. |
| The following code snippet shows how to do that:</p> |
| <pre>InputStream stream = ...; |
| IContentDescription description = contentTypeManager.getDescriptionFor(stream, "file.xml"); |
| stream.close();</pre> |
| <p>The returned <strong><a href="../reference/api/org/eclipse/core/runtime/content/IContentDescription.html">IContentDescription</a></strong> |
| instance describes the content type and additional relevant information extracted |
| from the contents provided. The content description stores content-specific |
| properties in form of key/value pairs. The platform itself is able to describe |
| properties such as the character set and the byte order of text-based streams, |
| but others can be defined by content type providers.</p> |
| <h3>Providing content-sensitive features</h3> |
| <p>New content types are often defined as specialization of existing ones. This |
| hierarchy establishes a "is a" relationship between a derived content |
| type and its base type. Plug-in developers must honor this when implementing |
| content sensitive features. If a given feature is applicable to a given content |
| type, the feature must be applicable to any derived content types as well. The |
| <strong>IContentType.isKindOf(IContentType superType) </strong>method allows |
| determining whether two <a href="../reference/api/org/eclipse/core/runtime/content/IContentType.html"><strong>IContentType</strong></a>s |
| are related. The method <strong>IContentType.getBaseType()</strong> allows determining |
| the base type of a given <a href="../reference/api/org/eclipse/core/runtime/content/IContentType.html"><strong>IContentType</strong></a>.</p> |
| </BODY> |
| </HTML> |
