The Annotating Pattern

Filesystem annotation mechanism, mentioned above, can be used for setting HTML names to any visual element that can render HTML:

• new JLabel( htmlName )
• TopComponent.setHtmlDisplayName( htmlName )=
• JComboBox.setRenderer( ... )
• Node
• and others

If client code does not access disk using FileObject (i.e. uses java.io.File instead) then actions are incorrecly enabled because in such case an internal status cache misses modifications events and reports original status.

The client code should be rewritten to FileObject usage. In some cases helps FileUtil.toFileObject(file).refresh().

    public Action[] getActions(boolean context) {
        ArrayList<Action> actions = new ArrayList <Action>();       
        actions.add(SystemAction.get(OpenAction.class));
        actions.add(SystemAction.get(RenameAction.class));

        // honor 57874 contact
        try {
            Repository repository  = Repository.getDefault();
            FileSystem sfs = repository.getDefaultFileSystem();
            FileObject fo = sfs.findResource("Projects/Actions");  // NOI18N
            if (fo != null) {
                DataObject dobj = DataObject.find(fo);
                FolderLookup actionRegistry = new FolderLookup((DataFolder)dobj);
                Lookup.Template query = new Lookup.Template(Object.class);
                Lookup lookup = actionRegistry.getLookup();
                Iterator it = lookup.lookup(query).allInstances().iterator();
                if (it.hasNext()) {
                    actions.add(null);
                }
                while (it.hasNext()) {
                    Object next = it.next();
                    if (next instanceof Action) {
                        actions.add(next);
                    } else if (next instanceof JSeparator) {
                        actions.add(null);
                    }
                 }
            }
        } catch (DataObjectNotFoundException ex) {
            // data folder for exiting fileobject expected
            ErrorManager.getDefault().notify(ex);
        }
        actions.add(SystemAction.get(PropertiesAction.class));
        Action[] retVal = new Action[actions.size()];
        actions.toArray(retVal);
        return retVal;
    }

public class UMLNode extends AbtractNode {
    private final FileObject fileObject;
    public UMLNode(UMLModel.Element model) {
         super(Lookups.singleton(model.getFileObject()));  // HERE
         this.fileObject = model.getFileObject();
         attachStatusListener(); // see bellow
    }

    // still in UMLNode class
    public Action[] getActions(boolean context) {
        ArrayList<Action> actions = new ArrayList <Action>();       
        actions.add(SystemAction.get(OpenAction.class));
        actions.add(SystemAction.get(RenameAction.class));
        actions.add(SystemAction.get(FileSystemAction.class));  // HERE
        actions.add(SystemAction.get(PropertiesAction.class));
        Action[] retVal = new Action[actions.size()];
        actions.toArray(retVal);
        return retVal;
    }

Project nodes use special case registration that is specific for them (it allows version control support module to show actions that make sense on projects only such as Update with Dependencies and Import Project into Repository). Your project nodes must honor contract #57874.

    // still in UMLNode class

    public String getDisplayName () {
        String s = super.getDisplayName ();

        try {
            s = fileObject().getFileSystem().getStatus()
            .annotateName(s, Collections.singleton(fileObject));
        } catch (FileStateInvalidException e) {
            // no fs, do nothing
        }

        return s;
    }

    public String getHtmlDisplayName() {
         try {
             FileSystem.Status stat = fileObject.getFileSystem().getStatus();
             if (stat instanceof FileSystem.HtmlStatus) {
                 FileSystem.HtmlStatus hstat = (FileSystem.HtmlStatus) stat;
                 
                 String result = hstat.annotateNameHtml (
                     super.getDisplayName(), Collections.singleton(fileObject));
                 
                 //Make sure the super string was really modified
                 if (!super.getDisplayName().equals(result)) {
                     return result;
                 }

                 // TODO attach status listener at the FileSystem 
                 // and on change refire PROP_DISPLAY_NAME
                 
             }
         } catch (FileStateInvalidException e) {
             //do nothing and fall through
         }
         return super.getHtmlDisplayName();
    }


    public java.awt.Image getIcon (int type) {
        java.awt.Image img = super.getIcon (type);

        try {
            img = model.getFileObject().getFileSystem().getStatus()
            .annotateIcon(img, type, Collections.singleton(fileObject));
        } catch (FileStateInvalidException e) {
            // no fs, do nothing
        }

        return img;
    }

    public java.awt.Image getOpenedIcon (int type) {
        java.awt.Image img = super.getIcon (type);

        try {
            img = model.getFileObject().getFileSystem().getStatus()
            .annotateIcon(img, type, Collections.singleton(fileObject));
        } catch (FileStateInvalidException e) {
            // no fs, do nothing
        }

        return img;
    }

    private void attachStatusListener() {
        FileSystem fs = fileObject.getFileSystem();
        FileStatusListener l = FileUtil.weakFileStatusListener(new FSL, fs)
        fs.addFileStatusListener(l);
    }

    private class FSL implements FileStatusListener {
        public void annotationChanged (FileStatusEvent ev) {
            if (ev.hasChanged(fileObject)) {
                if (ev.isNameChange()) {
                    if (refreshNameNodes == null) {
                        refreshNameNodes = new HashSet();
                    }
                    post |= refreshNameNodes.add(DataNode.this);
                }
                if (ev.isIconChange()) {
                    if (refreshIconNodes == null) {
                        refreshIconNodes = new HashSet();
                    }
                    post |= refreshIconNodes.add(DataNode.this);
                }
            }
        }
    }
}

Project Version Control Tutorial

The paper describes how to write own project types that support version control action. It applies to NetBeans^? 5.0 CVS support.

Typical Requirements

• Show context version control actions in project explorer
  • Put project under version control
  • Get latest version from reporitory
  • Inspect local changes
  • Commit local changes into repository
  • Search history

• Badge logical node icon and name
  • Mark modified and conflicting files by icon
  • Enhance name by revision information

Typical Solution

Version Control Action Context

• Project
  • Sources.TYPE_GENERIC
• NonRecursiveFolder
• FileObject
• DataObject

It means that version control actions (e.g. in main menu) are enabled on any node that has properly populated lookup. Actions depends on version control system e.g. for CVS:

• Import into repository (for unversioned)
• Show changes
• Update
• Diff
• Commit
• Ignore
• Search History
• Tag
• Switch to branch
• Merge with branch
• ...

Note that the version control actions are smart enough to distinguish whether project is under version control or not and they appear respectively.

Presenting Version Control Actions in Popup Menu

It means that any node that returns this action from popup menu contruction code receives version control actions submenu.

TODO why is there another mechanism for project nodes?

Annotating Logical Nodes

Any explorer node that represents a (set of) file(s) can use FileSystem.getStatus().annotateName(...) annotation support to annotate icon, display name and HTML display name and then listen on changes using org.openide.filesystems.FileStatusListener. Note that for HTML annotations you have to cast to FileSystem.HtmlStatus.

Summary

The developer implementing new org.openide.nodes.Node subclass can easily add support for executing and presenting version control actions; and can use the filesystem status annotation mechanism to alter icon and display name.

Since 5.0 there is no API that directly supports version control operations execution.

-- Main.pkuzel - 31 Jan 2006

TODO add code snippets