public final class Project extends HashStructureNode implements VetoableSubject
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.
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.
HashStructure
)
ListStructure
)
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.
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.
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.
addProjectChangeListener(java.lang.String,oracle.ide.model.ProjectChangeListener)
.
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.
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.
Node
s 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 Node
s
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.
HashStructure
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 |
LOG_READONLY
Constructor and Description |
---|
Project() |
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.
|
applyBatchChanges, closeImpl, copyToImpl, createDelegatingFilter, equalsImpl, getObjectStoreTarget, getProperties, getPropertiesForOverriding, getUserPropertiesOnly, invalidateCachedKeys, isUserPropertiesEnabled, newObjectStore, openImpl, saveImpl, saveUserProperties, setURL
add, equalsImpl, getBaseDirectory, getListOfChildren, getProperty, getProperty, getSharedPropertiesOnly, getURL, mayHaveChildren, remove, removeAll, removeAll, resetSubDirtyableOwners, revertImpl, setListOfChildren, setProperty, setSubDirtyableOwner, size, update
addNodeListener, addNodeListenerForType, addNodeListenerForTypeHierarchy, addWeakNodeListener, 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, removeWeakNodeListener, rename, renameImpl, reportOpenException, revert, runUnderReadLock, runUnderWriteLock, save, setEventLog, setMigrating, setOpen, setReadOnly, setTimestampDirectly, toString, tryRunUnderReadLock, tryRunUnderWriteLock, unsetMigrating, upgradeLock, upgradeUnlock, urlReadOnlyChanged, writeLock, writeLockCount, writeLockInterruptibly, writeUnlock
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
attach, detach, notifyObservers
getAttributes, getData
getAttributedLabel, getLongLabel, getShortLabel, getToolTipText, toString
public static final java.lang.String EXT
public static final java.lang.String DATA_KEY
Project
instance can be located
within a TraversableContext
. It is also
the key for the PropertiesDialog
.public static final java.lang.String NAMESPACE_URI
public static final java.lang.String ROOT_QNAME
public final javax.swing.Icon getIcon()
Node
Displayable
interface method. The Node class returns
a generic icon.getIcon
in interface Displayable
getIcon
in class Node
Icon
to be displayed for the
Displayable
.public final java.util.Iterator getChildren()
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)
}
getChildren
in interface Element
getChildren
in class DataContainer
Iterator
over any child Element
s
contained by this Element
. If there are no children,
null
is returned.Element.getChildren()
@Deprecated public final boolean canRemove(Element element)
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.
canRemove
in interface Folder
canRemove
in class DataContainer
element
- the Element
that is about to be removed
from this Folder
.true
Folder.canRemove(Element)
public final boolean canAdd(Element element)
Element
can be added to
this project.
This method does not allow the addition of Workspace
s and other
projects.canAdd
in interface Folder
canAdd
in class DataContainer
element
- the Element
that is about to be added
to this Folder
.true
if and only if the specified
Element
is not null
.Folder.canAdd(Element)
public final boolean containsChild(Element element)
containsChild
in interface Folder
containsChild
in class DataContainer
public final boolean remove(Element element, boolean notify)
remove
in class DataContainer
public final boolean add(Element element)
DataContainer
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.
add
in interface Folder
add
in class DataContainer
Folder.add(oracle.ide.model.Element)
public final boolean add(Node node, java.lang.String contentSetKey)
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.node
- the node to addcontentSetKey
- the key that identifies the content settrue
if the node was added successfully,
false
if the node could not be added to the specified
content set.java.lang.IllegalArgumentException
- if contentSetKey
does
not identify one of the registered ContentSetProviders.ContentSetProvider
public final boolean add(Node[] nodes, java.lang.String contentSetKey)
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.nodes
- the nodes to addcontentSetKey
- the key that identifies the content settrue
if all the nodes were added successfully,
false
if one or more nodes could not be added to the
specified content set.java.lang.IllegalArgumentException
- if contentSetKey
does
not identify one of the registered ContentSetProviders.ContentSetProvider
@Deprecated public final boolean add(Element element, boolean notify)
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).add
in class DataContainer
public final Workspace getWorkspace()
null
if a project has no
containing workspace.public final boolean isDefault()
HashStructureNode
true
if this Node is
the default instance.isDefault
in class HashStructureNode
@Deprecated public final boolean isDefaultProject()
@Deprecated public final java.util.Iterator findChildren(java.lang.Class childType)
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)
.
@Deprecated public final java.util.Iterator findChildren(java.lang.Class[] types)
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)
.
public static final void addProjectChangeListener(java.lang.String propertyName, ProjectChangeListener listener)
public static final void removeProjectChangeListener(java.lang.String propertyName, ProjectChangeListener listener)
public static final void removeProjectChangeListener(ProjectChangeListener listener)
public static void setCustomizedDefaults(HashStructure hash)
HashStructure
for details on what
placeholders are and how they are used.@Deprecated public final boolean containsOwnedChild(Element child)
false
.@Deprecated public final Folder findOwner(Element element)
null
@Deprecated public final void add(Node node, Node ownerNode)
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
.
@Deprecated public final java.util.Iterator findMyChildren(java.lang.Class childType)
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)
childType
- the Class representing the desired type@Deprecated public final java.util.Iterator findMyChildren(java.lang.Class[] types)
types
- an array of Class objects indicating the desired typespublic final void notifyVetoObservers(java.lang.Object subject, UpdateMessage change) throws ChangeVetoException
VetoableSubject
notifyVetoObservers
in interface VetoableSubject
subject
- the subject whose state has changed.change
- what changed.ChangeVetoException
- if any VetoObserver rejected the
pending change.public static final java.lang.String getDefaultName()
protected final HashStructureIO newHashStructureIO()
newHashStructureIO
in class HashStructureNode
protected final java.lang.String getNamespaceURI()
getNamespaceURI
in class HashStructureNode
protected final java.lang.String getRootQName()
getRootQName
in class HashStructureNode
protected final Subject createSubject()
Subject
implementation. This method
is called from Node.getSubject()
the first time the subject
is created. This implementation creates an IdeVetoableSubject
.createSubject
in class Node
public final boolean equals(java.lang.Object o)
equals
in class HashStructureNode
public int hashCode()
hashCode
in class DataContainer
public final java.lang.Object copyTo(java.lang.Object object)
copyTo
in class HashStructureNode