oracle.ide.model

Class NodeFactory

java.lang.Object

oracle.ide.model.NodeFactory

public final class NodeFactory
extends java.lang.Object

The NodeFactory class is responsible for creating instances of Node.

The type of Node that gets created depends on the URL that is passed into the findOrCreate(URL). The NodeFactory makes use of registered Recognizer instances to determine what Node class corresponds to a particular URL. Many nodes are simply recognized by the file extension while others are recognized only after a Recognizer reads the contents of the file/resource pointed by the URL. Because some Recognizers count on the physical file/resource to do their job, the findOrCreate(URL) method must only be called when the file/resource pointed by the URL physically exists on a file system/repository.

When the file/resource does not physically exists on the file system/repository, the findOrCreate(Class, URL) method must be called. The specified Class indicates what node type to create.

Every Node instance created by the NodeFactory is cached. An instance of an already created Node can be retrieved from the cache by calling the find(URL) method.

See Also:

Node, Recognizer

Field Summary

Fields

Modifier and Type	Field and Description
static int	NODE_CACHED Update message sent when a node is cached by a factory.
static int	NODE_UNCACHED Update message sent when a node is uncached by a factory.

Method Summary

Methods

Modifier and Type	Method and Description
static void	attach(Observer observer, java.lang.Class<? extends Node> type) Associates the specified observer with the given type.
static void	attach(Observer observer, java.lang.String type) Associates the specified observer with the given type.
static Node	clone(Node srcNode, java.net.URL dstNodeURL) Returns a new Node instance whose contents are identical to (and copied from) the specified Node.
static void	detach(Observer observer, java.lang.Class<? extends Node> type) Removes the specified observer from the given type list of observers.
static void	detach(Observer observer, java.lang.String type) Removes the specified observer from the given type list of observers.
static Node	find(java.net.URL url) Find the Node associated with the URL.
static Node	findInFolder(Folder folder, java.net.URL url) Deprecated. use the index model api. Since 11.1.1.0. The method does not scale well when large projects are involved. We now recommend clients use the Index Model API. This new API works asynchronously and performs very well, regardless of the project size, once the index model of the project files is constructed. See Index.findNodes( oracle.ide.index.QueryCriteria, Class, oracle.ide.index.ResultCallback)
static Node	findOrCreate(java.lang.Class<? extends Node> type, java.net.URL url) Use this method when creating a Node for a resource that does not yet exist at the location pointed to by the URL.
static Node	findOrCreate(java.net.URL url) Use this method when creating a Node for a resource that physically exists at the location pointed to by the URL.
static <T extends Node> T	findOrCreateOrFail(java.lang.Class<T> type, java.net.URL url) Find a node.
static Node	findOrCreateOrFail(java.net.URL url) Use this method when creating a Node for a resource that physically exists at the location pointed to by the URL.
static Node	findOrCreateUsingDefault(java.net.URL url, java.lang.Class<? extends Node> defaultNodeType) Avoid using this method.
static int	getCachedNodeCount() Gets the number of nodes currently cached.
static java.util.Iterator<Node>	getCachedNodes() Returns an Iterator over the Node instances that are currently cached.
static java.util.Iterator<Node>	getLoadedNodes() Returns an Iterator over the Node instances that are currently loaded.
static int	getOpenNodeCount() Gets the number of nodes currently open.
static java.util.Iterator<Node>	getOpenNodes() Returns an Iterator over the Node instances that are currently opened.
static void	recache(java.net.URL oldURL, java.net.URL newURL, Node node) Removes the oldURL from the cache and puts the newURL in the cache so that it is associated with the given Node.
static void	recache(java.net.URL oldURL, java.net.URL newURL, Node node, boolean notify) Removes the oldURL from the cache and puts the newURL in the cache so that it is associated with the given Node.
static java.lang.Class	recognizeUrl(java.net.URL url) Find the specified url in the cache or recognize it and return the Class instance of the Node that can be, or has been, created for this url.
static Node	uncache(java.net.URL url) Removes the Node with the specified URL from the NodeFactory's cache.
static Node	uncache(java.net.URL url, boolean notify) Removes the Node with the specified URL from the NodeFactory's cache.

Methods inherited from class java.lang.Object

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

Field Detail

NODE_CACHED

public static final int NODE_CACHED

Update message sent when a node is cached by a factory.

NODE_UNCACHED

public static final int NODE_UNCACHED

Update message sent when a node is uncached by a factory.

Method Detail

findOrCreateOrFail

public static Node findOrCreateOrFail(java.net.URL url)

Use this method when creating a Node for a resource that physically exists at the location pointed to by the URL.

When the URL points to a resource that does not exists, you must always use the findOrCreate(Class, URL) method.

Returns the Node associated with the URL. If the Node does not exist, a new Node is created.

Unlike findOrCreate(URL), this method handles exceptional cases using a RuntimeException, on the basis that most callers will be unable to do anything to recover from such a case. If you want to handle failed creation, using findOrCreate(URL)} is recommended.

Parameters:

url - unique URL identifying the node.

Returns:

an existing node or a newly created one. This method will not return null.

Throws:

java.lang.RuntimeException - if the node could not be created.

java.lang.NullPointerException - if url is null.

Since:

11.1.1

findOrCreate

public static Node findOrCreate(java.net.URL url)
                         throws java.lang.IllegalAccessException,
                                java.lang.InstantiationException

Use this method when creating a Node for a resource that physically exists at the location pointed to by the URL. When the URL points to a resource that does not exist, you must always use the findOrCreate(Class, URL) method. Returns the Node associated with the URL. If the Node does not exist, a new Node is created.

Parameters:

url - unique URL identifying the node.

Returns:

an existing node or a newly created one.

Throws:

java.lang.IllegalAccessException - if the Node class or its initializer is not accessible.

java.lang.InstantiationException - if the Node class is an abstract class, an interface, an array class, a primitive type, or void; or if the instantiation fails for some other reason.

findOrCreate

public static Node findOrCreate(java.lang.Class<? extends Node> type,
                java.net.URL url)
                         throws java.lang.IllegalAccessException,
                                java.lang.InstantiationException

Use this method when creating a Node for a resource that does not yet exist at the location pointed to by the URL. When the URL points to a resource that physically exists, you must always use the findOrCreate(URL) method. Returns the Node associated with the URL. If the Node does not exist, a new Node is created.

Parameters:

type - The Class of the node type to create.

url - URL identifying the node's persistent location.

Returns:

an existing Node or a newly created one.

Throws:

java.lang.IllegalAccessException - if the Class or its initializer is not accessible.

java.lang.InstantiationException - if the Class is an abstract class, an interface, an array class, a primitive type, or void; or if the instantiation fails for some other reason.

findOrCreateOrFail

public static <T extends Node> T findOrCreateOrFail(java.lang.Class<T> type,
                                    java.net.URL url)

Find a node. If it was not found, create it. If it could not be created, fail with a runtime exception.

Parameters:

type - the class of the node. Must not be null.

url - the url of the node. Must not be null.

Returns:

the node.

Throws:

java.lang.RuntimeException - if the node could not be created.

java.lang.ClassCastException - if the node exists but is not of type T.

java.lang.NullPointerException - if url or type are null.

Since:

11.0

findOrCreateUsingDefault

public static Node findOrCreateUsingDefault(java.net.URL url,
                            java.lang.Class<? extends Node> defaultNodeType)
                                     throws java.lang.IllegalAccessException,
                                            java.lang.InstantiationException

Avoid using this method. This method will be made private soon. URLs must be recognized by Recognizers. The IDE will use findOrCreate(URL) method to create Nodes for the URLs contained in a project's content. If Recognizers are not able to recognize your Node types, then the wrong node will be created. Only use methods findOrCreate(URL) and/or findOrCreate(Class, URL). Returns the Node associated with the URL. If the Node does not exist, a new Node is created.

Parameters:

url - unique URL identifying the node.

defaultNodeType - the default Node type to use if none of the recognizers can recognize the URL. Pass null to indicate that there is no default type, and that null should be returned if no recognizer can recognize the URL.

Returns:

an existing node or a newly created one.

Throws:

java.lang.IllegalAccessException - if the Node class or its initializer is not accessible.

java.lang.InstantiationException - if the Node class is an abstract class, an interface, an array class, a primitive type, or void; or if the instantiation fails for some other reason.

find

public static Node find(java.net.URL url)

Find the Node associated with the URL. If the Node does not exist, null is returned.

Parameters:

url - URL identifying the Node.

Returns:

An existing Node, or null if none exists.

findInFolder

public static Node findInFolder(Folder folder,
                java.net.URL url)

Deprecated. use the index model api. Since 11.1.1.0. The method does not scale well when large projects are involved. We now recommend clients use the Index Model API. This new API works asynchronously and performs very well, regardless of the project size, once the index model of the project files is constructed. See Index.findNodes( oracle.ide.index.QueryCriteria, Class, oracle.ide.index.ResultCallback)

Searches the specified Folder for an instance of Node whose URL matches the specified URL. If no such Node can be found, null is returned.

clone

public static Node clone(Node srcNode,
         java.net.URL dstNodeURL)

Returns a new Node instance whose contents are identical to (and copied from) the specified Node. The original Node is not modified. The copying is done based on the last saved state of the srcNode. The returned Node is cached and assigned the URL specified by dstNodeURL.

Parameters:

srcNode - The Node that will be cloned.

dstNodeURL - The URL that is to be assigned to the clone after all of its data has been loaded from the original. This is the URL under which the new Node will be cached by the NodeFactory.

Returns:

The new Node that is a clone of the srcNode.

uncache

public static Node uncache(java.net.URL url)

Removes the Node with the specified URL from the NodeFactory's cache.

WANING : Don't call this method unless you really know what what you are doing. (I.e. unless you know that you are exclusive owner of this node)
Calling this method can result in releasing a node that is held by another client. The next time somebody requests the same Node, she can obtain a different instance of Node for the same URL.

uncache

public static Node uncache(java.net.URL url,
           boolean notify)

Removes the Node with the specified URL from the NodeFactory's cache. If notify is true, it notifies observers that the node was uncached.

WANING : Don't call this method unless you really know what what you are doing. (I.e. unless you know that you are exclusive owner of this node)
Calling this method can result in releasing a node that is held by another client. The next time somebody requests the same Node, she can obtain a different instance of Node for the same URL.

recache

public static void recache(java.net.URL oldURL,
           java.net.URL newURL,
           Node node)

Removes the oldURL from the cache and puts the newURL in the cache so that it is associated with the given Node.

recache

public static void recache(java.net.URL oldURL,
           java.net.URL newURL,
           Node node,
           boolean notify)

Removes the oldURL from the cache and puts the newURL in the cache so that it is associated with the given Node.

getCachedNodes

public static java.util.Iterator<Node> getCachedNodes()

Returns an Iterator over the Node instances that are currently cached. There is no guarantee as to what order the Nodes will be iterated over.

Returns:

an iterator over nodes in the cache. The returned iterator is non-modifiable. Calling Iterator.remove() on the returned Iterator will throw UnsupportedOperationException.

getOpenNodes

public static java.util.Iterator<Node> getOpenNodes()

Returns an Iterator over the Node instances that are currently opened. There is no guarantee as to what order the Nodes will be iterated over.

Returns:

an iterator over open nodes. The return value is guaranteed not be be null. The iterator is non-modifiable. Its Iterator.remove() method will throw an UnsupportedOperationException.

getLoadedNodes

public static java.util.Iterator<Node> getLoadedNodes()

Returns an Iterator over the Node instances that are currently loaded. There is no guarantee as to what order the Nodes will be iterated over.

Returns:

an iterator over loaded nodes. The return value is guaranteed not be be null. The iterator is non-modifiable. Its Iterator.remove() method will throw an UnsupportedOperationException.

getCachedNodeCount

public static int getCachedNodeCount()

Gets the number of nodes currently cached.

getOpenNodeCount

public static int getOpenNodeCount()

Gets the number of nodes currently open.

attach

public static final void attach(Observer observer,
          java.lang.Class<? extends Node> type)

Associates the specified observer with the given type. Every time an instance of type is cached in the node factory, a NODE_CACHED notification is broadcast to the observer. The type should be the class of node and not of the data. The reason for this is that calling Node.getData() may break lazy loading for some nodes.

attach

public static final void attach(Observer observer,
          java.lang.String type)

Associates the specified observer with the given type. Every time an instance of type is cached in the node factory, a NODE_CACHED notification is broadcast to the observer. The type should be the class of node and not of the data. The reason for this is that calling Node.getData() may break lazy loading for some nodes.

detach

public static final void detach(Observer observer,
          java.lang.Class<? extends Node> type)

Removes the specified observer from the given type list of observers.

detach

public static final void detach(Observer observer,
          java.lang.String type)

Removes the specified observer from the given type list of observers.

recognizeUrl

public static java.lang.Class recognizeUrl(java.net.URL url)

Find the specified url in the cache or recognize it and return the Class instance of the Node that can be, or has been, created for this url. As a side-effect, this method will initialize the extension that defines the relevant Node type, if it hasn't been initialized yet.

Parameters:

url - A URL that needs finding or recognizing

Returns:

A Class instance or null if the URL was not found or recognized