oracle.ide.model

Class Recognizer

java.lang.Object

oracle.ide.model.Recognizer

Direct Known Subclasses:

AbstractFileContentRecognizerTemplate, FileContentPatternRecognizer, FileTypesRecognizer, 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Recognizer.DeclarativeDocumentInfo

Constructor Summary

Constructors

Constructor and Description
Recognizer()

Method Summary

Modifier and Type	Method and Description
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) Deprecated. replaced by FileTypesRecognizer.getClassNameForExtension(java.lang.String).
static ContentType	getContentTypeForExtension(java.lang.String extension) Deprecated. replaced by FileTypesRecognizer.getContentTypeForExtension(String).
static java.util.Map<java.io.File,MetaClass<?>>	getDeclarativeExtensionToClassMap()
static java.util.Map<java.io.File,ContentType>	getDeclarativeExtensionToContentTypeMap()
static java.lang.Class<? extends Node>	getDefaultNodeType() Returns the Node class that will be recognized when no Recognizer recognizes a given URL.
static MetaClass<? extends Node>	getDefaultNodeTypeAsMeta() Returns the Node meta class that will be recognized when no Recognizer recognizes a given URL and when the calling code queries recognizer through metaclasses.
static Recognizer	getDefaultRecognizer() Returns the default Recognizer.
static DocumentInfo	getDocumentInfo(java.lang.Class nodeClass)
static DocumentInfo	getDocumentInfo(java.lang.String nodeClassName)
static DocumentInfo	getDocumentInfoForDeclarativeEntries(java.lang.String nodeClassName)
static java.util.Map	getExtensionToClassMap() Deprecated. Causes excessive extension loading to occur. Use getExtensionToMetaClassMap() instead.
static java.util.Map	getExtensionToContentTypeMap()
static java.util.Map<java.io.File,MetaClass>	getExtensionToMetaClassMap() Get the mapping from file extension to meta class.
protected static java.util.logging.Logger	getLogger()
static boolean	isXmlExtension(java.lang.String extension) Asks whether the given extension is registered to be handled by the IDE's built-in XML recognizer.
static void	mapExtensionToClass(java.lang.String extension, java.lang.Class cls) Deprecated. replaced by declarative registration through a node-recognizers-hook/url-recognizer/file-extension trigger hook.
static void	mapExtensionToContentType(java.lang.String extension, ContentType contentType) Deprecated. replaced by declarative registration through a node-recognizers-hook/url-recognizer/extension-to-content-type trigger hook.
static void	mapExtensionToMetaClass(java.lang.String extension, MetaClass cls) Maps a file extension to a Node class.
static void	mapExtensionToXML(java.lang.String extension) Registers the specified extension to be handled by the IDE's built-in XML recognizer.
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.
MetaClass<? extends Node>	recognizeAsMeta(java.net.URL url) This method allows gets the MetaClass of a recognized Node.
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 MetaClass<? extends Node>	recognizeURLAsMeta(java.net.URL url) Returns the MetaClass of the Node that should be instantiated for the specified url.
static MetaClass<? extends Node>	recognizeURLAsMeta(java.net.URL url, MetaClass<? 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) Deprecated. replaced by declarative registration through a node-recognizers-hook/document-infos/document-info trigger hook.
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 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.

recognizeAsMeta

public MetaClass<? extends Node> recognizeAsMeta(java.net.URL url)

This method allows gets the MetaClass of a recognized Node. This is useful for cases in which the classloader of a metaclass is not the same as the real classloader of the node class. It may also be useful, for cases when we need to get the MetaClass of a recognized node without initializing the node extensions.

Parameters:

url - unique URL identifying the document.

Returns:

the Node type as a MetaClass 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

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

Deprecated. replaced by declarative registration through a node-recognizers-hook/url-recognizer/file-extension trigger hook.

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.

mapExtensionToMetaClass

public static void mapExtensionToMetaClass(java.lang.String extension,
                                           MetaClass cls)

Maps a file extension to a Node class. Extensions should typically use the node-recognizers-hook, url-recognizer, and file-extension hooks instead of this method. This method is for special cases where an a file extension class is registered from another extension.

Parameters:

extension - the file extension

cls - the meta class for the Node class

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.

getDefaultNodeTypeAsMeta

public static MetaClass<? extends Node> getDefaultNodeTypeAsMeta()

Returns the Node meta class that will be recognized when no Recognizer recognizes a given URL and when the calling code queries recognizer through metaclasses.

isXmlExtension

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

Asks whether the given extension is registered to be handled by the IDE's built-in XML recognizer.

Parameters:

extension - the extension.

Returns:

a verdict on whether the extension is treated as XML.

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.

recognizeURLAsMeta

public static MetaClass<? extends Node> recognizeURLAsMeta(java.net.URL url)

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

recognizeURL

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

recognizeURLAsMeta

public static MetaClass<? extends Node> recognizeURLAsMeta(java.net.URL url,
                                                           MetaClass<? extends Node> defaultNodeType)

getExtensionToClassMap

@Deprecated
public static final java.util.Map getExtensionToClassMap()

Deprecated. Causes excessive extension loading to occur. Use getExtensionToMetaClassMap() instead.

Returns:

An unsynchronized Map that should be synchronized upon when used.

getExtensionToMetaClassMap

public static final java.util.Map<java.io.File,MetaClass> getExtensionToMetaClassMap()

Get the mapping from file extension to meta class.

Returns:

the mapping from file extension to meta class

getDeclarativeExtensionToClassMap

public static final java.util.Map<java.io.File,MetaClass<?>> getDeclarativeExtensionToClassMap()

getExtensionToContentTypeMap

public static final java.util.Map getExtensionToContentTypeMap()

Returns:

An unsynchronized Map that should be synchronized upon when used.

getDeclarativeExtensionToContentTypeMap

public static final java.util.Map<java.io.File,ContentType> getDeclarativeExtensionToContentTypeMap()

getDocumentInfo

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

getDocumentInfo

public static final DocumentInfo getDocumentInfo(java.lang.String nodeClassName)

getDocumentInfoForDeclarativeEntries

public static final DocumentInfo getDocumentInfoForDeclarativeEntries(java.lang.String nodeClassName)

getClassForExtension

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

Deprecated. replaced by FileTypesRecognizer.getClassNameForExtension(java.lang.String).

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

getContentTypeForExtension

@Deprecated
public static ContentType getContentTypeForExtension(java.lang.String extension)

Deprecated. replaced by FileTypesRecognizer.getContentTypeForExtension(String).

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

mapExtensionToContentType

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

Deprecated. replaced by declarative registration through a node-recognizers-hook/url-recognizer/extension-to-content-type trigger hook.

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

registerDocumentInfo

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

Deprecated. replaced by declarative registration through a node-recognizers-hook/document-infos/document-info trigger hook.

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.

getLogger

protected static java.util.logging.Logger getLogger()