org.eclipse.wst.common.componentcore.resources
Interface IVirtualResource

All Known Subinterfaces:

IVirtualComponent, IVirtualContainer, IVirtualFile, IVirtualFolder

public interface IVirtualResource

Allows clients to work with flexible project structures using API similar to the Eclipse Platform IResource model.

IVirtualResource allows resources to be accessed through a abstract path referred to as a "runtime path". A virtual resource may represent multiple underlying resources. A virtual resource is contained by exactly one component. A resource may be represented by multiple virtual resources, which may be contained by one or more components.

IVirtualResource allows clients to acquire information about the underlying resource including the name, and the paths which are relevant to the current resource, such as the runtime path, the workspace-relative path of the underlying resource, and the project-relative path of the underlying resource.

Each IVirtualResource can represent an implicit reference or an explicit reference. An explicit reference is a formal mapping from some path within the file structure to a runtime path. Changing or removing an explicit reference only requires model modifications. An implicit reference has a root which is derived from an explicit path, but some fragment of the path towards the end is derived from the literal path within the file structure. Modifications to implicit paths may cause changes to structure on disk. For resource modifications that should not modify structures on disk, use IGNORE_UNDERLYING_RESOURCE.

This interface is not intended to be implemented by clients.

Since:

1.0

Field Summary

static int	COMPONENT Type constant (bit mask value 64) which identifies the root resource.
static int	FILE Type constant (bit mask value 16) which identifies file resources.
static int	FOLDER Type constant (bit mask value 32) which identifies folder resources.
static int	FORCE Update flag constant (bit mask value 256) indicating that the operation should proceed even if the resource is out of sync with the local file system.
static int	IGNORE_EXCLUSIONS Indicates that exclusions enumerated in the model should be ignored.
static int	IGNORE_UNDERLYING_RESOURCE Indicates that modifications should only modify the metamodel and ignore the underlying resources where applicable.
static int	NONE General purpose zero-valued bit mask constant.

Method Summary

void	createLink(IPath aProjectRelativeLocation, int updateFlags, IProgressMonitor monitor) Create a mapping from the supplied location to the runtime path of this virtual resource.
void	delete(int updateFlags, IProgressMonitor monitor) Remove the resource from the flexible structure.
boolean	equals(java.lang.Object other) Compares two objects for equality; for resources, equality is defined in terms of their handles: same resource type, equal full paths, and identical workspaces.
boolean	exists() Returns whether this virtual resource is backed by an accessible IResource.
IVirtualComponent	getComponent() Returns the name of the component that contains this virtual resource.
java.lang.String	getFileExtension() Returns the file extension portion of this virtual resource's name, or null if it does not have one.
java.lang.String	getName() Returns the name of this virtual resource.
IVirtualContainer	getParent() Returns the virtual resource which contains this virtual resource, or null if it has no parent (that is, the virtual resource represents the root of the component).
IProject	getProject() Returns the project which contains the component which contains this virtual resource.
IPath	getProjectRelativePath() Returns a relative path of the underlying resource with respect to its project.
java.lang.String	getResourceType() The resourceType provides meta-information about the types of content this virtual resource may represent.
IPath	getRuntimePath() Returns the runtime path of this virtual resource.
int	getType() Returns the type of this resource.
IResource	getUnderlyingResource() A virtual resource is a representation of one or more Eclipse Platform resources.
IResource[]	getUnderlyingResources() A virtual resource is a representation of one or more Eclipse Platform resources.
IPath	getWorkspaceRelativePath() Returns the full, absolute path of the underlying resource relative to the workspace.
boolean	isAccessible() Returns whether this resource is accessible.
void	setResourceType(java.lang.String aResourceType) The resourceType provides meta-information about the types of content this virtual resource may represent.

Field Detail

FILE

public static final int FILE

Type constant (bit mask value 16) which identifies file resources.

See Also:

getType(), IVirtualFile, Constant Field Values

FOLDER

public static final int FOLDER

Type constant (bit mask value 32) which identifies folder resources.

See Also:

getType(), IVirtualFolder, Constant Field Values

COMPONENT

public static final int COMPONENT

Type constant (bit mask value 64) which identifies the root resource.

See Also:

getType(), IVirtualContainer, Constant Field Values

NONE

public static final int NONE

General purpose zero-valued bit mask constant. Useful whenever you need to supply a bit mask with no bits set.

Example usage:

 delete(IVirtualResource.NONE, null)
 

Since:

2.0

See Also:

Constant Field Values

FORCE

public static final int FORCE

Update flag constant (bit mask value 256) indicating that the operation should proceed even if the resource is out of sync with the local file system.

Since:

2.0

See Also:

Constant Field Values

IGNORE_EXCLUSIONS

public static final int IGNORE_EXCLUSIONS

Indicates that exclusions enumerated in the model should be ignored. (bit mask value 512)

See Also:

Constant Field Values

IGNORE_UNDERLYING_RESOURCE

public static final int IGNORE_UNDERLYING_RESOURCE

Indicates that modifications should only modify the metamodel and ignore the underlying resources where applicable. See the documentation on references for more information on why this flag is relevant. (bit mask value 1024)

See Also:

Constant Field Values

Method Detail

createLink

public void createLink(IPath aProjectRelativeLocation,
                       int updateFlags,
                       IProgressMonitor monitor)
                throws CoreException

Create a mapping from the supplied location to the runtime path of this virtual resource. Model changes will occur as a result of this method, and potentially resource-level creations as well.

Parameters:

aProjectRelativeLocation - A project relative location that will be represented by the runtime path after this call

updateFlags - A bitmask of flags to supply to the method.

monitor -

Throws:

CoreException

delete

public void delete(int updateFlags,
                   IProgressMonitor monitor)
            throws CoreException

Remove the resource from the flexible structure. Removing the resource could require changes to the underlying metamodel or changes to the file structure. To avoid changes the actual disk structure, use IGNORE_UNDERLYING_RESOURCE.

Update flags supplied to this method will be passed into any IResource modification API which is called as a result of this method's invocation.

Throws:

CoreException

See Also:

IGNORE_UNDERLYING_RESOURCE, IResource#delete(int, org.eclipse.core.runtime.IProgressMonitor)

equals

public boolean equals(java.lang.Object other)

Compares two objects for equality; for resources, equality is defined in terms of their handles: same resource type, equal full paths, and identical workspaces. Resources are not equal to objects other than resources.

Parameters:

other - the other object

Returns:

an indication of whether the objects are equals

See Also:

getType(), getWorkspaceRelativePath()

exists

public boolean exists()

Returns whether this virtual resource is backed by an accessible IResource.

IVirtualResource objects are lightweight handle objects used to access IResources. However, having an IVirtualResource handle does not necessarily mean the underlying resource represented by the handle exists in the workspace, or is accessible. For more detailed information concerning the existence or accessibility of the underlying resource, getUnderlyingResource().

Returns:

true if the underlying resource exists and is accessible, otherwise false

See Also:

org.eclipse.core.resources.IResource#exists(), #getUnderlyingResource();

getFileExtension

public java.lang.String getFileExtension()

Returns the file extension portion of this virtual resource's name, or null if it does not have one. The file extension of the virtual resource will be returned, which may or may not match that of the underlying resource.

The file extension portion is defined as the string following the last period (".") character in the name. If there is no period in the name, the path has no file extension portion. If the name ends in a period, the file extension portion is the empty string.

This is a resource handle operation; the resource need not exist.

Returns:

a string file extension

See Also:

getName()

getWorkspaceRelativePath

public IPath getWorkspaceRelativePath()

Returns the full, absolute path of the underlying resource relative to the workspace.

This is a resource handle operation; the resource need not exist. If this resource does exist, its path can be safely assumed to be valid.

Returns:

the absolute path of this resource

See Also:

getProjectRelativePath(), IResource#getFullPath()

getProjectRelativePath

public IPath getProjectRelativePath()

Returns a relative path of the underlying resource with respect to its project.

This is a resource handle operation; the resource need not exist. If this resource does exist, its path can be safely assumed to be valid.

Project-relative paths are recommended over absolute paths, since the former are not affected if the project is renamed.

Returns:

the relative path of this resource with respect to its project

See Also:

getWorkspaceRelativePath(), getProject(), IResource#getProjectRelativePath()

getRuntimePath

public IPath getRuntimePath()

Returns the runtime path of this virtual resource. The runtime path is determined through the metamodel and represents the path that the underlying resource will be accessed at runtime.

Returns:

the runtime path of this virtual resource

getName

public java.lang.String getName()

Returns the name of this virtual resource. The name of a virtual resource is synonymous with the last segment of its runtime path.

This is a resource handle operation; the resource need not exist.

If this resource exists, its name can be safely assumed to be valid.

Returns:

the name of the virtual resource

See Also:

getRuntimePath()

getComponent

public IVirtualComponent getComponent()

Returns the name of the component that contains this virtual resource.

Each virtual resource is contained by at least one component. A component represents a logical collection of files. If the underlying resource is contained by multiple components, then the component name returned by this method will be determined by how the virtual resource was created. For each virtual resource, the component name will be the same as the component name of the parent.

Returns:

the name of the component that contains the virtual resource

getParent

public IVirtualContainer getParent()

Returns the virtual resource which contains this virtual resource, or null if it has no parent (that is, the virtual resource represents the root of the component).

The full path of the parent resource is the same as this resource's full path with the last segment removed.

This is a resource handle operation; neither the resource nor the resulting resource need exist.

Returns:

the container of the virtual resource, or null if this virtual resource represents the root of the component

getProject

public IProject getProject()

Returns the project which contains the component which contains this virtual resource.

The name of the project may not (and most likely will not) be referenced in the runtime path of this virtual path, but will be referenced by the workspace-relative path.

This is a resource handle operation; neither the resource nor the resulting project need exist.

Returns:

the project handle

getType

public int getType()

Returns the type of this resource. The returned value will be one of FILE, FOLDER, COMPONENT

• All resources of type FILE implement IVirtualFile.
• All resources of type FOLDER implement IVirtualFolder.
• All resources of type COMPONENT implement IVirtualContainer.

This is a resource handle operation; the resource need not exist in the workspace.

Returns:

the type of this resource

See Also:

FILE, FOLDER, COMPONENT

getUnderlyingResource

public IResource getUnderlyingResource()

A virtual resource is a representation of one or more Eclipse Platform resources.

Returns the "primary" underlying resource. The resource may or may not exist. The resource will be contained by the project returned by getProject().

Since a virtual resource could represent multiple resources, this method will return the "primary" resource. For clients that wish to take advantage of the multiple resources at a single path, use getUnderlyingResources().

Returns:

The primary resource that backs this virtual resource.

getUnderlyingResources

public IResource[] getUnderlyingResources()

A virtual resource is a representation of one or more Eclipse Platform resources.

Returns all underlying resources. The resources may or may not exist. The resources will be contained by the project returned by getProject().

Since a virtual resource could represent multiple resources, this method will return all underlying resources. For clients that prefer to acknowledge only one resource, at a single path, use getUnderlyingResource().

Returns:

All resources that back this virtual resource.

isAccessible

public boolean isAccessible()

Returns whether this resource is accessible. For files and folders, this is equivalent to existing; for projects, this is equivalent to existing and being open. The workspace root is always accessible.

Returns:

true if this resource is accessible, and false otherwise

See Also:

exists(), IProject#isOpen()

getResourceType

public java.lang.String getResourceType()

The resourceType provides meta-information about the types of content this virtual resource may represent. Examples include "java", "resources", "bpel", etc.

The resourceType may be null, and IVirtualComponent will always return null for this method.

Returns:

A client-set resourceType string

setResourceType

public void setResourceType(java.lang.String aResourceType)

The resourceType provides meta-information about the types of content this virtual resource may represent. Examples include "java", "resources", "bpel", etc.

The resourceType may be null, and IVirtualComponent will always return null for this method.