oracle.ide.model
Class Recognizer

java.lang.Object
  oracle.ide.model.Recognizer

Direct Known Subclasses:

XMLRecognizer

public abstract class Recognizer
extends java.lang.Object

The Recognizer class is the IDE mechanism by which URLs are mapped to Node types. A Recognizer is also responsible for creating a Node, once its URL is recognized. The IDE framework provides two built-in ways to recognize a URL:

• By the file extension of the URL (URL recognizer).
• By the XML document type (XML recognizer).

To configure the URL recognizer to map a specific file extension to a Node type, use the method mapExtensionToClass(String,Class).

To configure the XML recognizer to map an XML document type to a Node type, see XMLRecognizer. There are methods in XMLRecognizer for recognizing based on the doctype declaration, the root element name (with or without namespace URI), and schema instance URI.

If the mapping of a URL to a Node type is more complex than what the IDE provides by default, there is an API for registering custom Recognizer implementations via one of the following methods:

• registerRecognizer(String,Recognizer)
• registerRecognizer(String[],Recognizer)
• registerLowPriorityRecognizer(Recognizer)

A custom Recognizer is given priority ahead of the IDE's built-in XML and URL recognizers as long as it is registered in association with a file extension. When it is registered without an associated file extension using registerLowPriorityRecognizer(Recognizer), the custom Recognizer is not evaluated until after the IDE's built-in XML and URL recognizers.

When none of the custom, XML, or URL recognizers is able to map a URL to a Node type, the IDE may make a final attempt to recognize the URL based on byte signatures. If that fails, then the URL is mapped to UnrecognizedTextNode.

Node Type Conversion

The Recognizer class is also responsible for maintaining a registry of legal Node type conversions. This registry is used when the user attempts to rename an existing Node. If renaming the Node changes the type of the Node, the conversion must be registered with Recognizer or else the IDE will deny the request to rename the Node. See registerConversion(Class,Class) for details.

Constructor Summary

Recognizer()

Method Summary

boolean	canConvert(java.net.URL oldURL, java.net.URL newURL) Check if the old URL can be converted to the new URL.
Node	create(java.net.URL url, java.lang.Class nodeType) This method creates a Node instance of the specified type with the specified URL.
static Recognizer	findRecognizer(java.net.URL url) Returns the instance of Recognizer that is able to specify the Node class that should be instantiated for the given URL.
static java.lang.Class	getClassForExtension(java.lang.String extension) Return the class that has been registered with the given extension or null if not has been registered.
static ContentType	getContentTypeForExtension(java.lang.String extension) Returns the ContentType associated with the given extension.
static java.lang.Class<? extends Node>	getDefaultNodeType() Returns the Node class that will be recognized when no Recognizer recognizes a given URL.
static Recognizer	getDefaultRecognizer() Returns the default Recognizer.
static DocumentInfo	getDocumentInfo(java.lang.Class nodeClass)
static java.util.Map	getExtensionToClassMap()
static java.util.Map	getExtensionToContentTypeMap()
protected static boolean	isXmlExtension(java.lang.String extension)
static void	mapExtensionToClass(java.lang.String extension, java.lang.Class cls) Maps the given extension, which is a file extension, to the given Class which must be a Node class.
static void	mapExtensionToContentType(java.lang.String extension, ContentType contentType) Maps the given extension, which is a file extension, to the given ContentType.
static void	mapExtensionToXML(java.lang.String extension) Registers the specified extension to be handled by the IDE's built-in XML recognizer.
abstract java.lang.Class<? extends Node>	recognize(java.net.URL url) This method implements the fundamental responsibility of a Recognizer -- to map a URL to a Node type.
static java.lang.Class<? extends Node>	recognizeURL(java.net.URL url) Returns the Class of the Node that should be instantiated for the specified url.
static java.lang.Class<? extends Node>	recognizeURL(java.net.URL url, java.lang.Class<? extends Node> defaultNodeType)
static void	registerConversion(java.lang.Class<? extends Node> oldNodeType, java.lang.Class<? extends Node> newNodeType) Registers a conversion between Node classes that is to be considered valid.
static void	registerDocumentInfo(java.lang.Class nodeClass, DocumentInfo info) Associates a document class with a record of information containing the icon and label identifying the document type.
static void	registerLowPriorityRecognizer(Recognizer recognizer) This method allows a Recognizer to be registered without an associated file extension.
static void	registerRecognizer(java.lang.String[] fileExtensions, Recognizer recognizer) Registers the specified file extensions so that an URL that ends with one of the specified extensions is recognized using the specified Recognizer, so long as no earlier Recognizer has already recognized the URL.
static void	registerRecognizer(java.lang.String fileExtension, Recognizer recognizer) Registers the specified file extension so that an URL that ends with it is recognized using the specified Recognizer, so long as no earlier Recognizer has already recognized the URL.
static java.io.File	sanitizeExtension(java.lang.String extension) Makes sure that the extension begins with a '.'.
static void	setDefaultRecognizer(Recognizer recognizer) Sets the default Recognizer.
java.net.URL	validate(java.net.URL newURL, java.net.URL oldURL) Validate the specified new name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Recognizer

public Recognizer()

Method Detail

recognize

public abstract java.lang.Class<? extends Node> recognize(java.net.URL url)

This method implements the fundamental responsibility of a Recognizer -- to map a URL to a Node type. Efficient implementation of this method is essential for the IDE's performance. In particular, I/O operations should be avoided or deferred as much as possible. If a Recognizer does not recognize a particular URL, this method must return null. The returned Class representing the Node type is later passed to the create(URL,Class) method which creates the Node instance.

Parameters:

url - unique URL identifying the document.

Returns:

the Node type as a Class object.

create

public Node create(java.net.URL url,
                   java.lang.Class nodeType)
            throws java.lang.IllegalAccessException,
                   java.lang.InstantiationException

This method creates a Node instance of the specified type with the specified URL. If the type is null, then the returned Node is also null.

Parameters:

url - unique URL identifying the document.

nodeType - the type of the Node. The specified Class object must represent a type of Node, or else a ClassCastException will occur.

Returns:

The design-time Node.

Throws:

java.lang.IllegalAccessException

java.lang.InstantiationException

validate

public java.net.URL validate(java.net.URL newURL,
                             java.net.URL oldURL)
                      throws RecognizerException

Validate the specified new name. Returns null if the name does not validate. This method may modify the URL to make it valid, such as adding a file extension. The old URL is used as the validation base. For example, if the new URL does not have the correct file extension, the old URL extension may be added to the new URL during the validation process.

Parameters:

newURL - the new URL to validate.

oldURL - the old URL used as the validation base.

Returns:

the validated URL or null if the name does not validate.

Throws:

RecognizerException - if validation fails. The reason why validation failed is in the exception's message. The message should be suitably formatted so that it can be displayed to the user.

canConvert

public boolean canConvert(java.net.URL oldURL,
                          java.net.URL newURL)

Check if the old URL can be converted to the new URL. This method is called on the new URL's Recognizer. It is called when a Node is being renamed and the new name causes a Node type conversion. If the call to canConvert(URL, URL) returns true, the Node conversion will go through, otherwise, it will not. The base implementation looks at the two URLs to see what the corresponding Node class will be. If the conversion is compatible, then it is allowed. Compatibility is tested by checking the Node class types that have been registered through registerConversion(Class, Class). If a mapping from the oldURL's recognized Node class can be found to the newURL's recognized Node class, then this method returns true. Otherwise, this method returns false.

Of course, if the Node class for the oldURL and the newURL are identical, then conversion is allowed.

Parameters:

oldURL - the url of the node being renamed.

newURL - the new url for the node.

Returns:

true if conversion is possible.

mapExtensionToClass

public static void mapExtensionToClass(java.lang.String extension,
                                       java.lang.Class cls)

Maps the given extension, which is a file extension, to the given Class which must be a Node class.

Addins that extend this class must provide their own static implementation of this method. Using the default implementation for any other purpose than to map extension defined by end users to registered node types will break current IDE behavior. In other words, this method is only for internal IDE purposes. The extension passed in is allowed to contain or omit the leading "."; if it is omitted, it will be added automatically.

mapExtensionToXML

public static void mapExtensionToXML(java.lang.String extension)

Registers the specified extension to be handled by the IDE's built-in XML recognizer.

registerRecognizer

public static void registerRecognizer(java.lang.String fileExtension,
                                      Recognizer recognizer)

Registers the specified file extension so that an URL that ends with it is recognized using the specified Recognizer, so long as no earlier Recognizer has already recognized the URL.

Parameters:

fileExtension - The file extension to recognize. The extension may or may not begin with '.' but an extension is presumed to follow a '.' in the URL. So, for example, calling registerRecognizer("txt", MyRecognizer); will cause "file:/C:/readme.txt" to be recognized by MyRecognizer, but not "file:/C:/readmetxt".

recognizer - The Recognizer that handles the recognition of a URL with the specified file extension.

registerRecognizer

public static void registerRecognizer(java.lang.String[] fileExtensions,
                                      Recognizer recognizer)

Registers the specified file extensions so that an URL that ends with one of the specified extensions is recognized using the specified Recognizer, so long as no earlier Recognizer has already recognized the URL.

Parameters:

fileExtensions - The file extensions to recognize. The extensions may or may not begin with '.' but an extension is presumed to follow a '.' in the URL. So, for example, calling registerRecognizer(new String[]{"txt"}, MyRecognizer); will cause "file:/C:/readme.txt" to be recognized by MyRecognizer, but not "file:/C:/readmetxt".

recognizer - The Recognizer that handles the recognition of a URL with the specified file extension.

registerLowPriorityRecognizer

public static void registerLowPriorityRecognizer(Recognizer recognizer)

This method allows a Recognizer to be registered without an associated file extension. The lack of an associated file extension places the Recognizer into a low priority queue that is only evaluted if no other Recognizer associated with a file extension has recognized the file. The only way to increase the priority of a Recognizer registration is to associate a file extension with it and use registerRecognizer(String,Recognizer) or registerRecognizer(String[],Recognizer).

Parameters:

recognizer - The low-priority Recognizer to register.

getDefaultRecognizer

public static Recognizer getDefaultRecognizer()

Returns the default Recognizer. The default Recognizer is the last Recognizer to be called.

setDefaultRecognizer

public static void setDefaultRecognizer(Recognizer recognizer)

Sets the default Recognizer. The default Recognizer is the last Recognizer to be called.

getDefaultNodeType

public static java.lang.Class<? extends Node> getDefaultNodeType()

Returns the Node class that will be recognized when no Recognizer recognizes a given URL.

isXmlExtension

protected static boolean isXmlExtension(java.lang.String extension)

registerConversion

public static final void registerConversion(java.lang.Class<? extends Node> oldNodeType,
                                            java.lang.Class<? extends Node> newNodeType)

Registers a conversion between Node classes that is to be considered valid.

Parameters:

oldNodeType - The Node class that the conversion is occuring from.

newNodeType - The Node class that the oldNodeType is being converted to.

findRecognizer

public static Recognizer findRecognizer(java.net.URL url)

Returns the instance of Recognizer that is able to specify the Node class that should be instantiated for the given URL. If no Recognizer can determine the Node class, then null is returned.

recognizeURL

public static java.lang.Class<? extends Node> recognizeURL(java.net.URL url)

Returns the Class of the Node that should be instantiated for the specified url. If no Recognizer can determine the Node class, then the value of getDefaultNodeType() is returned.

recognizeURL

public static java.lang.Class<? extends Node> recognizeURL(java.net.URL url,
                                                           java.lang.Class<? extends Node> defaultNodeType)

getExtensionToClassMap

public static final java.util.Map getExtensionToClassMap()

Returns:

An unsynchronized Map that should be synchronized upon when used.

getExtensionToContentTypeMap

public static final java.util.Map getExtensionToContentTypeMap()

Returns:

An unsynchronized Map that should be synchronized upon when used.

getDocumentInfo

public static final DocumentInfo getDocumentInfo(java.lang.Class nodeClass)

getClassForExtension

public static final java.lang.Class getClassForExtension(java.lang.String extension)

Return the class that has been registered with the given extension or null if not has been registered.

getContentTypeForExtension

public static final ContentType getContentTypeForExtension(java.lang.String extension)

Returns the ContentType associated with the given extension. If no ContentType association has been registered, this method returns null.

mapExtensionToContentType

public static final void mapExtensionToContentType(java.lang.String extension,
                                                   ContentType contentType)

Maps the given extension, which is a file extension, to the given ContentType.

registerDocumentInfo

public static final void registerDocumentInfo(java.lang.Class nodeClass,
                                              DocumentInfo info)

Associates a document class with a record of information containing the icon and label identifying the document type.

sanitizeExtension

public static final java.io.File sanitizeExtension(java.lang.String extension)

Makes sure that the extension begins with a '.'. If it does, the extension is just returned as-is. If it doesn't, one is prepended to the extension, and the result is returned. The extension is returned as a File to make the extension follow the case-sensitivity rules of the local file system.