oracle.ide.model

Class Project

java.lang.Object

oracle.ide.model.Node

oracle.ide.model.DataContainer

oracle.ide.model.HashStructureNode

oracle.ide.model.Project

All Implemented Interfaces:

Displayable, Element, Folder, LazyLoadable, Locatable, Observer, Subject, VetoableSubject, Dirtyable, PropertyStorage

public final class Project
extends HashStructureNode
implements VetoableSubject

This class represents a user project in the IDE. Generally defined, a Project is a collection of persistent, hierarchical, cascading properties with a batch-capable change notification mechanism. For typesafe property access, there is a recommended approach using adapters.

Persistence

The entry point for getting and setting project properties is the HashStructureNode.getProperties() method, which returns a HashStructure. Any changes made to the HashStructure are automatically persisted by the IDE in an XML format mediated by HashStructureIO. All URL objects stored in the HashStructure are automatically persisted as being relative to the Project's URL, if possible. If no relative path is possible or if the relative path involves ascending to the root of the file system, the absolute URL is persisted instead.

Hierarchical Structure

Project properties are hierarchical in nature. There are two structures that compose the hierarchy:

• an unordered collection of named properties (HashStructure)
• an ordered collection of unnamed properties (ListStructure)

The root of the Project's properties is a HashStructure. Both structures can hold certain types of "leaf" properties such as String, URL, int, boolean, and a few others. Full details of the supported types are documented in HashStructure and ListStructure.

By convention, instead of storing leaf properties directly in the root HashStructure, an IDE extension writer should group properties specific to an extension together in their own HashStructure and put that into the Project's root HashStructure. This will help avoid name collisions, isolate any migration issues to the relevent sub-HashStructure, and facilitate support for cascading properties and typesafe adapters.

Cascading Order

The Project class also distinguishes two levels of properties: shared and user-specific. "Shared" refers to those properties that are stored in the project file, which is often source-controlled and used in a team environment. If a property change needs to be pushed out to other team members using the same project file, that property must be stored as a shared property. In contrast, "user-specific" refers to a customization to a shared property that a user wants to change, usually temporariliy, without having to checkout the project from source control. The ability to keep shared and user-specific properties separate but have property lookups give precedence to user-specific property values is referred to as "cascading" properties.

There are three methods for retrieving a HashStructure, providing different angles on cascading:

• DataContainer.getSharedPropertiesOnly() returns a HashStructure that contains only the shared properties. User-specific properties are not visible in this HashStructure.
• HashStructureNode.getUserPropertiesOnly() returns a HashStructure that contains only user-specific properties. Shared properties are not visible in this HashStructure.
• HashStructureNode.getProperties() returns a single cascading HashStructure for both the shared and user-specific property values. Write operations are only applied to the user-specific side. See HashStructureNode.getProperties() for the details.

Clients that only read properties should use HashStructureNode.getProperties(). Clients that write properties have an extra aspect to consider - changes to shared properties may have an impact on team development, possibly including merge conflicts on the project file. Therefore, the decision to save a shared property needs to be considered carefully with respect to team development impact. The Project API is intentionally designed to bias toward saving properties as user-specific. This design forces a developer to have to code to DataContainer.getSharedPropertiesOnly() in order to persist shared project properties.

Change Notification

Whenever a property value is added, changed, or removed, Project automatically fires a change event. To register a listener for property changes, use addProjectChangeListener(java.lang.String,oracle.ide.model.ProjectChangeListener).

Batching Change Notifications

Because project property changes tend to come in batches, there is an API method for specifying that change notifications should be temporarily buffered and fired all together sometime later. The API is HashStructureNode.applyBatchChanges(java.lang.Runnable). While the Runnable is executing, all change events are buffered rather than fired. When the runnable completes, either normally or by throwing, all change events are fired together in one large event.

Typesafe Property Access Using Adapters

The Project class is declared final. Allowing subtyping would actually decrease flexibility, since the IDE's Project file must work properly even when loaded by different combinations of IDE extensions. If Project subtyping were allowed, the persistence would become more complicated, and interoperability would be hindered rather than enhanced, since extensions would rely on typecasting, such as after calling Context.getProject(), which would fail with ClassCastException when extensions compete for what the exact subtype of the Project should be. Therefore, to avoid these design pitfalls, the Project class is final and will remain final.

Instead, we prescribe a different approach for typesafe access to project properties using adapters. To access a specific property, you attach (or wrap) an adapter to the Project and call methods on the adapter to perform the storage and retrieval operations on the underlying HashStructure. Usually, the fully-qualified name of the adapter is the name of the sub-HashStructure that the adapter operates on. Whenever possible, this is an important naming convention to follow, because it simplifies the process of locating the adapter class when you looking at the persisted project file. For example, consider this project file:

    <jpr:project xmlns:jpr="http://xmlns.oracle.com/ide/project">
       <hash n="oracle.jdeveloper.compiler.OjcConfiguration">
          <value n="internalEncoding" v="Cp1252"/>
       </hash>
       <hash n="oracle.jdeveloper.model.J2eeSettings">
          <value n="j2eeWebAppName" v="Application1-Web-webapp"/>
          <value n="j2eeWebContextRoot" v="Application1-Web-context-root"/>
          <hash n="webContentSet">
             <list n="url-path">
                <url path="public_html/"/>
             </list>
          </hash>
       </hash>
       <hash n="oracle.jdeveloper.model.PathsConfiguration">
          <hash n="javaContentSet">
             <list n="pattern-filters">
                <string v="+**"/>
             </list>
             <list n="url-path">
                <url path="public_html/WEB-INF/src/"/>
             </list>
          </hash>
       </hash>
    </jpr:project>

There are three "hash" elements at the first (root) level of properties. Their names, such as oracle.jdeveloper.compiler.OjcConfiguration, are actually the fully-qualified names of the HashStructureAdapter class responsible for each sub-hash. Although not technically required at the API level, this is very helpful convention to follow for making the contents of the project file easier to learn and understand.

For example, to retrieve the Java content set of a project:

      import oracle.ide.model.ContentSet;
      import oracle.jdeveloper.model.PathsConfiguration;

      //  Attach the adapter.
      PathsConfiguration config = PathsConfiguration.getInstance(project);

      //  Get the Java ContentSet.
      ContentSet javaContentSet = config.getJavaContentSet();

In the above example, PathsConfiguration is a type of HashStructureAdapter. The ContentSet returned by getJavaContentSet() is itself another HashStructureAdapter.

Another example, having to do with getting the libraries of a Project:

      import oracle.jdeveloper.model.JProjectLibraries;
      import oracle.jdeveloper.library.JDK;
      import oracle.jdeveloper.library.JLibrary;

      //  Attach the adapter.
      JProjectLibraries projLibs = JProjectLibraries.getInstance(project);

      //  Get the Project's JDK.
      JDK jdk = projLibs.getJDK();

      //  Get an array of the libraries referenced by this Project.
      JLibrary[] libs = projLibs.getLibraries();

Note: Starting 07/01/2008 the owner map is deprecated without replacement. Comments below are no longer relevant, left for reference of legacy code. All additions and updates to the owner map are now no-ops.

Owner Map

A project may contain children owned by other Nodes which are part of the same project. "Owned" in this context means that the owner Node has final veto power over whether a child Node can be added, removed, moved, or renamed. In the Application Navigator, owned Nodes are usually not displayed and are instead represented by a composite node for the owner.

The relationship between a container Node and any Nodes it owns is maintained by the project owner map. To specify that a Node has an owner within the Project, clients should use the method add(oracle.ide.model.Node, oracle.ide.model.Node).

The Node-to-owner relationship is maintained by the project and persited in the project file. Both the Node and owner must be a Node, because the NodeFactory is used to load them from the persisted data. Owner Nodes must be direct children of the Project.

See Also:

HashStructure

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DATA_KEY The data key by which a Project instance can be located within a TraversableContext.
static java.lang.String	EXT
static java.lang.String	NAMESPACE_URI
static java.lang.String	ROOT_QNAME

Fields inherited from class oracle.ide.model.Node

LOG_READONLY

Constructor Summary

Constructors

Constructor and Description
Project()

Method Summary

Modifier and Type	Method and Description
boolean	add(Element element) Part of the Folder interface.
boolean	add(Element element, boolean notify) Deprecated. since 11.0 (07/01/2008)
boolean	add(Node[] nodes, java.lang.String contentSetKey) Adds the nodes to the project, specifically adding it to the content set identified by the content set key.
void	add(Node node, Node ownerNode) Deprecated. 07/01/2008: owner maps are deperecated without replacement. This method is now a no-op.
boolean	add(Node node, java.lang.String contentSetKey) Adds the node to the project, specifically adding it to the content set identified by the content set key.
static void	addProjectChangeListener(java.lang.String propertyName, ProjectChangeListener listener)
boolean	canAdd(Element element) Call this method to determine if an Element can be added to this project.
boolean	canRemove(Element element) Deprecated. since 11.0 (07/01/2008)
boolean	containsChild(Element element) Returns true if the child is contained by the project even if the owner is another folder contained in the project.
boolean	containsOwnedChild(Element child) Deprecated. since 11.0 (07/01/2008) owner maps are deperecated without replacement.
java.lang.Object	copyTo(java.lang.Object object)
protected Subject	createSubject() Creates an instance of a Subject implementation.
boolean	equals(java.lang.Object o)
java.util.Iterator	findChildren(java.lang.Class childType) Deprecated. since 11.0 (07/01/2008)
java.util.Iterator	findChildren(java.lang.Class[] types) Deprecated. since 11.0 (07/01/2008)
java.util.Iterator	findMyChildren(java.lang.Class childType) Deprecated. 07/01/2008
java.util.Iterator	findMyChildren(java.lang.Class[] types) Deprecated.
Folder	findOwner(Element element) Deprecated. since 11.0 (07/01/2008) owner maps are deperecated without replacement.
java.util.Iterator	getChildren() This method should not be used for getting project children.
static java.lang.String	getDefaultName() Returns the default name (prefix only) for project files in general.
javax.swing.Icon	getIcon() Displayable interface method.
protected java.lang.String	getNamespaceURI()
protected java.lang.String	getRootQName()
Workspace	getWorkspace() Get the workspace this project is open in.
int	hashCode()
boolean	isDefault() For HashStructureNode subtypes that keep default state in a separate Node instance, this method should return true if this Node is the default instance.
boolean	isDefaultProject() Deprecated. Use isDefault().
protected HashStructureIO	newHashStructureIO()
void	notifyVetoObservers(java.lang.Object subject, UpdateMessage change) Notifies all observers that the state of the subject has changed.
boolean	remove(Element element, boolean notify)
static void	removeProjectChangeListener(ProjectChangeListener listener)
static void	removeProjectChangeListener(java.lang.String propertyName, ProjectChangeListener listener)
static void	setCustomizedDefaults(HashStructure hash) Sets the specified HashStructure as the source for customized default values for the project.

Methods inherited from class oracle.ide.model.HashStructureNode

applyBatchChanges, closeImpl, copyToImpl, createDelegatingFilter, equalsImpl, getObjectStoreTarget, getProperties, getPropertiesForOverriding, getUserPropertiesOnly, invalidateCachedKeys, isUserPropertiesEnabled, newObjectStore, openImpl, saveImpl, saveUserProperties, setURL

Methods inherited from class oracle.ide.model.DataContainer

add, equalsImpl, getBaseDirectory, getListOfChildren, getProperty, getProperty, getSharedPropertiesOnly, getURL, mayHaveChildren, remove, removeAll, removeAll, resetSubDirtyableOwners, revertImpl, setListOfChildren, setProperty, setSubDirtyableOwner, size, update

Methods inherited from class oracle.ide.model.Node

addNodeListener, addNodeListenerForType, addNodeListenerForTypeHierarchy, attach, beginThreadNodeUsageCycle, callUnderReadLock, callUnderWriteLock, close, delete, deleteImpl, detach, endThreadNodeUsage, endThreadNodeUsageCycle, ensureOpen, equalsImpl, getAttributes, getData, getInputStream, getLongLabel, getShortLabel, getSubject, getTimestamp, getTimestampLoadedUnsafe, getToolTipText, getTransientProperties, getUnmodifiedTimestamp, isDirty, isLoaded, isLockHeld, isMigrating, isNew, isOpen, isReadLocked, isReadLockHeld, isReadOnly, isReadOrWriteLocked, isTrackedInNodeCache, isTrackingThreadNodeUsage, isWriteLocked, isWriteLockHeld, lockCount, markDirty, markDirtyImpl, nodeLock, notifyObservers, open, readLock, readLockCount, readLockInterruptibly, readUnlock, refreshTimestamp, removeNodeListener, removeNodeListenerForType, removeNodeListenerForTypeHierarchy, rename, renameImpl, reportOpenException, revert, runUnderReadLock, runUnderWriteLock, save, setEventLog, setMigrating, setOpen, setReadOnly, setTimestampDirectly, toString, tryRunUnderReadLock, tryRunUnderWriteLock, unsetMigrating, upgradeLock, upgradeUnlock, urlReadOnlyChanged, writeLock, writeLockCount, writeLockInterruptibly, writeUnlock

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface oracle.ide.model.Subject

attach, detach, notifyObservers

Methods inherited from interface oracle.ide.model.Element

getAttributes, getData

Methods inherited from interface oracle.ide.model.Displayable

getLongLabel, getShortLabel, getToolTipText, toString

Field Detail

EXT

public static final java.lang.String EXT

See Also:

Constant Field Values

DATA_KEY

public static final java.lang.String DATA_KEY

The data key by which a Project instance can be located within a TraversableContext. It is also the key for the PropertiesDialog.

See Also:

Constant Field Values

NAMESPACE_URI

public static final java.lang.String NAMESPACE_URI

See Also:

Constant Field Values

ROOT_QNAME

public static final java.lang.String ROOT_QNAME

See Also:

Constant Field Values

Constructor Detail

Project

public Project()

Method Detail

getIcon

public final javax.swing.Icon getIcon()

Description copied from class: Node

Displayable interface method. The Node class returns a generic icon.

Specified by:

getIcon in interface Displayable

Overrides:

getIcon in class Node

Returns:

the Icon to be displayed for the Displayable.

getChildren

public final java.util.Iterator getChildren()

This method should not be used for getting project children. 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 oracle.ide.index.Index#findNodes( oracle.ide.index.QueryCriteria, oracle.ide.index.ResultCallback)

Specified by:

getChildren in interface Element

Overrides:

getChildren in class DataContainer

Returns:

an Iterator over any child Elements contained by this Element. If there are no children, null is returned.

See Also:

Element.getChildren()

canRemove

@Deprecated
public final boolean canRemove(Element element)

Deprecated. since 11.0 (07/01/2008)

Call this method to determine if the element can be removed from this project. If the specified element is not a Node, this method returns true. If it is a node and it has an owner, it delegates the call to the Folder owner. It the node does not have an owner, implying that the project owns the node, this method returns true.

Note: With the deprecation of the owner map, all reference to owner and owner map are irrelevant.

Specified by:

canRemove in interface Folder

Overrides:

canRemove in class DataContainer

Parameters:

element - the Element that is about to be removed from this Folder.

Returns:

true

See Also:

Folder.canRemove(Element)

canAdd

public final boolean canAdd(Element element)

Call this method to determine if an Element can be added to this project. This method does not allow the addition of Workspaces and other projects.

Specified by:

canAdd in interface Folder

Overrides:

canAdd in class DataContainer

Parameters:

element - the Element that is about to be added to this Folder.

Returns:

true if and only if the specified Element is not null.

See Also:

Folder.canAdd(Element)

containsChild

public final boolean containsChild(Element element)

Returns true if the child is contained by the project even if the owner is another folder contained in the project.

Specified by:

containsChild in interface Folder

Overrides:

containsChild in class DataContainer

remove

public final boolean remove(Element element,
                            boolean notify)

Overrides:

remove in class DataContainer

add

public final boolean add(Element element)

Description copied from class: DataContainer

Part of the Folder interface. The specified Element is added to the end of the child list. However, if the Element is null, this method does nothing.

No notification is fired by this method.

Specified by:

add in interface Folder

Overrides:

add in class DataContainer

See Also:

Folder.add(oracle.ide.model.Element)

add

public final boolean add(Node node,
                         java.lang.String contentSetKey)

Adds the node to the project, specifically adding it to the content set identified by the content set key. The supplied key must match one of the ContentProviders registered with the project. If the key is valid but the node cannot be added to that content set, the node will be added to the Resources content set, if possible.

Parameters:

node - the node to add

contentSetKey - the key that identifies the content set

Returns:

true if the node was added successfully, false if the node could not be added to the specified content set.

Throws:

java.lang.IllegalArgumentException - if contentSetKey does not identify one of the registered ContentSetProviders.

See Also:

ContentSetProvider

add

public final boolean add(Node[] nodes,
                         java.lang.String contentSetKey)

Adds the nodes to the project, specifically adding it to the content set identified by the content set key. The supplied key must match one of the ContentProviders registered with the project. If the key is valid but the node cannot be added to that content set, the node will be added to the Resources content set, if possible.

Parameters:

nodes - the nodes to add

contentSetKey - the key that identifies the content set

Returns:

true if all the nodes were added successfully, false if one or more nodes could not be added to the specified content set.

Throws:

java.lang.IllegalArgumentException - if contentSetKey does not identify one of the registered ContentSetProviders.

See Also:

ContentSetProvider

add

@Deprecated
public final boolean add(Element element,
                                     boolean notify)

Deprecated. since 11.0 (07/01/2008)

This method no longer has any effect on the Project. Use AddContentCommand to make sure that files appear in a project under the right content set, and also be sure that newly created files are saved (this will also trigger the UpdateMessage.CHILD_ADDED event automatically).

Overrides:

add in class DataContainer

getWorkspace

public final Workspace getWorkspace()

Get the workspace this project is open in. A project can only be open in one workspace at a time. May return null if a project has no containing workspace.

Returns:

the workspace

isDefault

public final boolean isDefault()

Description copied from class: HashStructureNode

For HashStructureNode subtypes that keep default state in a separate Node instance, this method should return true if this Node is the default instance.

Overrides:

isDefault in class HashStructureNode

isDefaultProject

@Deprecated
public final boolean isDefaultProject()

Deprecated. Use isDefault().

findChildren

@Deprecated
public final java.util.Iterator findChildren(java.lang.Class childType)

Deprecated. since 11.0 (07/01/2008)

This method should not be used for finding project children. 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 oracle.ide.index.Index#findNodes( oracle.ide.index.QueryCriteria, oracle.ide.index.ResultCallback).

findChildren

@Deprecated
public final java.util.Iterator findChildren(java.lang.Class[] types)

Deprecated. since 11.0 (07/01/2008)

This method should not be used for finding project children. 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 oracle.ide.index.Index#findNodes( oracle.ide.index.QueryCriteria, oracle.ide.index.ResultCallback).

Returns:

an iterator to all project children

addProjectChangeListener

public static final void addProjectChangeListener(java.lang.String propertyName,
                                                  ProjectChangeListener listener)

removeProjectChangeListener

public static final void removeProjectChangeListener(java.lang.String propertyName,
                                                     ProjectChangeListener listener)

removeProjectChangeListener

public static final void removeProjectChangeListener(ProjectChangeListener listener)

setCustomizedDefaults

public static void setCustomizedDefaults(HashStructure hash)

Sets the specified HashStructure as the source for customized default values for the project. These are initialized into every Project instance as placeholder values in the Project's actual HashStructure. See HashStructure for details on what placeholders are and how they are used.

containsOwnedChild

@Deprecated
public final boolean containsOwnedChild(Element child)

Deprecated. since 11.0 (07/01/2008) owner maps are deperecated without replacement.

Returns true if the child is contained by the project even if the owner is another folder contained in the project.

Returns:

false.

findOwner

@Deprecated
public final Folder findOwner(Element element)

Deprecated. since 11.0 (07/01/2008) owner maps are deperecated without replacement.

Returns:

null

add

@Deprecated
public final void add(Node node,
                                  Node ownerNode)

Deprecated. 07/01/2008: owner maps are deperecated without replacement. This method is now a no-op.

Add the node to the project, specifying ownerNode as its owner. For this method to return successfully, the ownerNode must also be a Folder. If the node already had an owner in this Project when this method is called, the method does nothing.

Once this method is successful, a call to findOwner(Element) with the node as its argument will return the ownerNode.

findMyChildren

@Deprecated
public final java.util.Iterator findMyChildren(java.lang.Class childType)

Deprecated. 07/01/2008

Retrieves children of a specific type owned by the project. Unlike getChildren, children owned by folders within the project will not be returned. The list of owned children is filtered to include only those children of the specified type.

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 oracle.ide.index.Index#findNodes( oracle.ide.index.QueryCriteria, oracle.ide.index.ResultCallback)

Parameters:

childType - the Class representing the desired type

Returns:

an Iterator over the filtered child list, guaranteed not to be null.

findMyChildren

@Deprecated
public final java.util.Iterator findMyChildren(java.lang.Class[] types)

Deprecated.

Retrieves the children that are one of the specified types owned by the project. UnlikegetChildren, children owned by folders within the project will not be returned.

Parameters:

types - an array of Class objects indicating the desired types

Returns:

an Iterator over the Project's children that includes only those elements whose type (or supertype) is one of the specified types.

notifyVetoObservers

public final void notifyVetoObservers(java.lang.Object subject,
                                      UpdateMessage change)
                               throws ChangeVetoException

Description copied from interface: VetoableSubject

Notifies all observers that the state of the subject has changed.

Specified by:

notifyVetoObservers in interface VetoableSubject

Parameters:

subject - the subject whose state has changed.

change - what changed.

Throws:

ChangeVetoException - if any VetoObserver rejected the pending change.

getDefaultName

public static final java.lang.String getDefaultName()

Returns the default name (prefix only) for project files in general.

newHashStructureIO

protected final HashStructureIO newHashStructureIO()

Overrides:

newHashStructureIO in class HashStructureNode

getNamespaceURI

protected final java.lang.String getNamespaceURI()

Overrides:

getNamespaceURI in class HashStructureNode

getRootQName

protected final java.lang.String getRootQName()

Overrides:

getRootQName in class HashStructureNode

createSubject

protected final Subject createSubject()

Creates an instance of a Subject implementation. This method is called from Node.getSubject() the first time the subject is created. This implementation creates an IdeVetoableSubject.

Overrides:

createSubject in class Node

equals

public final boolean equals(java.lang.Object o)

Overrides:

equals in class HashStructureNode

hashCode

public int hashCode()

Overrides:

hashCode in class DataContainer

copyTo

public final java.lang.Object copyTo(java.lang.Object object)

Specified by:

copyTo in class HashStructureNode