Eclipse resource management

Outline Introduction Basic resource management Further resource management

Introduction Package org.eclipse.core.resources Define the notions of workspaces and resources Provides basic support for managing a workspace and its resources for resource plug- in Resource retrieve, create, delete, move..Etc. Tracking resource lifecycle changes Similar to a file system

Basic resource management Resource and the workspace Resource and the local file system Resource properties

Resource and the workspace Workspace : central hub of user ’ s file Plug-in use resource API to create, navigate, manipulate resource in the workspace Three kinds of resource Project Folder file

Resources (I) Project Collection of folders and files Organize resources related to specific projects Interface IProject Folder Contains other folder and files Like directory in file system Interface IFolder

Resource (II) File Arbitrary sequence of bytes Interface IFile Interface Iworkspace Interface IResource

Resource organization Tree structure Project at top Folder and file underneath Workspace root

Resource and file system When resource plug-in is activate, the workspace is represented by an instance of IWorkspace The IWorkspace instance represent all files and directories in file system Get the IWorkspace instance : ResourcePlugin.getWorkspace();

Manipulate resource First get the IWorkspaceRoot instance, which represents the root of the resource tree in the workspace Access projects in the workspace Access folders and files in projects Access files in folders Similar to java.io.File

Get and open project IWorkspaceRoot myWorkspaceRoot = ResourcesPlugin.getWorkspace().getRoot(); IProject myWebProject = myWorkspaceRoot.getProject("MyWeb"); // open if necessary if (myWebProject.exists() && !myWebProject.isOpen()) myWebProject.open(null);

Get folder, create file IFolder imagesFolder = myWebProject.getFolder("images"); if (imagesFolder.exists()) { // create a new file IFile newLogo = imagesFolder.getFile("newLogo.gif"); FileInputStream fileStream = new FileInputStream( "c:/MyOtherData/newLogo.gif"); newLogo.create(fileStream, false, null); // create closes the file stream, so no worries. }

File copy IFile logo = imagesFolder.getFile("logo.gif"); if (logo.exists()) { IPath newLogoPath = new Path("newLogo.gif"); logo.copy(newLogoPath, false, null); IFile newLogo = imagesFolder.getFile("newLogo.gif");... }

File move IFolder newImagesFolder = myWebProject.getFolder("newimages"); newImagesFolder.create(false, true, null); IPath renamedPath = newImagesFolder.getFullPath().append("renamedLogo.gif"); newLogo.move(renamedPath, false, null); IFile renamedLogo = newImagesFolder.getFile("renamedLogo.gif");

Resource and real file location Use IResource.getLocation() to get the full system path of a resource Use IProjectDescription.setLocation() to change a project location Get a resource via a file system path IWorkspaceRoot.getFileForLocation() IWorkspaceRoot.getContainerForLocation()

Resource properties Session properties Cache information in key-value pair in memory Lost when a resource is deleted or the project or workspace is closed Persistent properties Store resource-specific information on disk Store with system metadata and maintained across platform shutdown and restart

Used Interface and class Class ResourcePlugin The plug-in run-time class The start point for resource manipulation Interface IWorkspace Represent the workspace in the platform Interface IResource The resource in the workspace Superinterface of IFile, IFolder, IProject, IWorkspaceRoot

Used interface and class Interface IFile, IFolder, IProject, IWorkspaceRoot System resource instance Provide manipulation methods of resources Interface IProjectDescription Contain the metadata require to define a project Contain the information in file.project with all projects

Further resource management Resource markers Tracking resource changes Incremental project builders Workspace save participation Project natures Derived resource Resource modification hooks

Marker Like a small tag to a resource Record information about a problem or a task, or simply record a location as bookmark User can jump to the marked location within a resource Platform defined five standard markers (marker, taskmarker, problemmark,bookmark,textmark)

Resource API defines methods for creating, setting value, extending the platform with new marker type Platform manage markers, it will throw away markers attached to resource that are deleted Plug-in control marker ’ s creation, removal and attribute value. It also removes markers that no longer apply to a resource Interface IMarker

Marker operation Marker creation Using factory method IResource.createMarker() Ex: IMarker marker = file.createMarker(IMarker.TASK); Marker deletion Ex: try { marker.delete(); } catch (CoreException e) { // Something went wrong }

Batch delete int depth = IResource.DEPTH_INFINITE; try { resource.deleteMarkers(IMarker.PROBLEM, true, depth); } catch (CoreException e) { // something went wrong } Attribute setting if (marker.exists()) { try { marker.setAttribute(IMarker.MESSAGE, "A sample marker message"); marker.setAttribute(IMarker.PRIORITY, IMarker.PRIORITY_HIGH); } catch (CoreException e) { // You need to handle the case where the marker no longer exists } }

Querying markers Resource can be queried for their markers and the markers of their children IMarker[] problems = null; int depth = IResource.DEPTH_INFINITE; try { problems = resource.findMarkers(IMarker.PROBLEM, true, depth); } catch (CoreException e) { // something went wrong }

Extension platform with new marker type New marker type are derived from existing ones using multiple inheritance, it will inherit all of the attribute from supertypes Plug-ins must declare new marker type in plugin.xml before using it Persistent Markers saved when workspace is saved.

point="org.eclipse.core.resources.markers" />

public IMarker createMyMarker(IResource resource){ try { Imarker marker= resource.createMarker("com.example.markers.myproblem "); marker.setAttribute("myAttribute", "MYVALUE"); return marker; } catch (CoreException e) { // You need to handle the cases where attribute value is rejected } }

Tracking resource changes The resource API include a event mechanism for resource changes Use IResourceChangeListener and IResourceChangeEvent to track resource change Method that create, delete or change a resource typically trigger a resource change event

Must register a resource change listener with the workspace IResourceChangeListener listener = new MyResourceChangeReporter(); ResourcesPlugin.getWorkspace().addResourceChangeListener( liste ner, IResourceChangeEvent.POST_CHANGE); Use IWorkspace.run(runnable,monitor) can batch the change operation, resource change event will be triggered once when the runnable is completed

Resource deltas Resource change event contains a resource delta that describes the net effect of change Structured as a tree rooted at the workspace root Describe four type of resource change Created, deleted, or changed Moved or renamed via IResource.move() Marker that has been added, removed, or changed Files that has been modified

To traverse a resource tree, implement the interface IResourceDeltaVisitor or using IResourceDelta.getAffectedChildren()

Resource change event PRE_CLOSE PRE_DELETE PRE_AUTOBUILD POST_AUTOBUILE POST_CHANGE

Implementing a resource change listener IResourceChangeListener listener = new MyResourceChangeReporter(); ResourcesPlugin.getWorkspace().addResourceChangeListener(listener, IResourceChangeEvent.PRE_CLOSE | IResourceChangeEvent.PRE_DELETE | IResourceChangeEvent.PRE_AUTO_BUILD| IResourceChangeEvent.POST_AUTO_BUILD | IResourceChangeEvent.POST_CHANGE);

public class MyResourceChangeReporter implements IResourceChangeListener { public void resourceChanged(IResourceChangeEvent event) { IResource res = event.getResource(); switch (event.getType()) { case IResourceChangeEvent.PRE_CLOSE: System.out.print("Project "); System.out.print(res.getFullPath()); System.out.println(" is about to close."); break; case IResourceChangeEvent.PRE_DELETE: System.out.print("Project "); System.out.print(res.getFullPath()); System.out.println(" is about to be deleted."); break; case IResourceChangeEvent.POST_CHANGE: System.out.println("Resources have changed."); event.getDelta().accept(new DeltaPrinter()); break; } } }

Incremental project builder Manipulate the resource in a project in a fashion defined by the builder itself Often used to apply a transformation on a resource to produce a resource or other kind Platform define two kind of builds Full build Incremental build

Incremental builds are seeded with a resource change delta to reflect the net effect of all resource change

Invoke a build A build can be invoked in two ways IProject.build() for the reciving project IWorkspace.build() for all open project in the workspace An incremental project builders are also invoked implicitly by the platform during an auto-build

Defining an incremental project builder <builder

public class BuilderExample extends IncrementalProjectBuilder{ IProject[] build(int kind, Map args, IProgressMonitor monitor) throws CoreException { // add your build logic here return null; } Protected void startupOnInitialize() { // add builder init logic here } }

Builder implementation protected IProject[] build(int kind, Map args, IProgressMonitor monitor throws CoreException { if (kind == IncrementalProjectBuilder.FULL_BUILD) { fullBuild(monitor); } //full build else { IResourceDelta delta = getDelta(getProject()); if (delta == null) { fullBuild(monitor); } // auto build else { incrementalBuild(delta, monitor); } } return null; }

protected void fullBuild(final IProgressMonitor monitor) throws CoreException { try { getProject().accept(new MyBuildVisitor()); } catch (CoreException e) { } } class MyBuildVisitor implements IResourceVisitor { public boolean visit(IResource res) { //build the specified resource. //return true to continue visiting children. return true; }

protected void incrementalBuild(IResourceDelta delta, IProgressMonitor monitor) throws CoreException { // the visitor does the work. delta.accept(new MyBuildDeltaVisitor()); }

Association an incremental project builder with a project IProjectDescription desc = project.getDescription(); ICommand[] commands = desc.getBuildSpec(); boolean found = false; for (int i = 0; i < commands.length; ++i) { if (commands[i].getBuilderName().equals(BUILDER_ID)) { found = true; break; } } if (!found) { //add builder to project ICommand command = desc.newCommand(); command.setBuilderName(BUILDER_ID); ICommand[] newCommands = new ICommand[commands.length + 1];

// Add it before other builders. System.arraycopy(commands, 0, newCommands, 1, commands.length); newCommands[0] = command; desc.setBuildSpec(newCommands); project.setDescription(desc, null); }

Workspace save participation Plug-in can participate in workspace save process to save plug-in data To participate in saving, add a save participation to the workspace in plug-in startup() method ResourcesPlugin.getWorkspace().addSaveParticipa nt(this, saveParticipant);

Save participation implementation Interface ISaveParticipant defines the protocol for a workspace save participation Provide behavior for different stages of the save process Implement method for each stage

Saving steps prepareToSave Notify the participant the workspace is about to be saved, it should suspend normal operation saving Tell the participant to save its important state

doneSaving Notifies the participant that the workspace has been saved and the participant can continue normal operation rollback Tells the participant to rollback the important state because the save operation has failed

Project natures Allow a plug-in to tag a project as a specific kink of project A project can have more then one nature Special constrains for the nature One-of-nature Requires-nature Interface IProjectNature

Defining a nature <extension point="org.eclipse.core.resources.natures" id="myNature" name="My Nature">

Implement a nature public class MyNature implements IProjectNature { private IProject project; public void configure() throws CoreException { // Add nature-specific information // for the project, such as adding a builder // to a project's build spec. } public void deconfigure() throws CoreException { // Remove the nature-specific information here. } public IProject getProject() { return project; } public void setProject(IProject value) { project = value; } }

Associate a nature to a project try { IProjectDescription description = project.getDescription(); String[] natures = description.getNatureIds(); String[] newNatures = new String[natures.length + 1]; System.arraycopy(natures, 0, newNatures, 0, natures.length); newNatures[natures.length] = "com.example.natures.myNature"; description.setNatureIds(newNatures); project.setDescription(description, null); } catch (CoreException e) { // Something went wrong }

Derived resources Resources that are not original data, and can be recreated from their source files Use IResource.setDerived(boolean) to indicate that a resource is derived Use IResource.isDerived() to determine a resource is derived

Resource modification hooks Enable the team support plug-in