1. Data Objects & Editors
David Strupl
Staff Engineer
Sun Microsystems

2. Agenda DataObject Factories Presentation Editor APIs Schliemann Lexer
Folding
Highlighting
Code completion
...
We will talk about:
- analogy between NB and OS/2
- what are DataObjects, what are they good for
- how are they created (factories)
- how are they visualized
- and their content is typically edited in editors, so few words about editor support in NB platform

3. DataObject Logical object around a FileObject
Understands the file's content
Copy, move, shadow, createFromTemplate
Can represent multiple files (not recommended)
Factories
A module installs a DataLoader for a particular file type
Usually registered by MIME type + file extension
That loader is a factory for DataObjects for that type of file
- DataObject inspired by OS/2 principles (so the ghost of OS/2 is still here! :)
- DO is logical layer “above” FileObject
- DO is always associated with actions that can be done with it
- DO can encapsulate multiple files
- DO x FO difference: FO is API, can be just called, used. DO must be created by developer in DataLoader (which is something like “factory method” for DO)
- Tool model – current leading OS (Win, Ubuntu, Mac); user finds application for action and uses it
- Document model – OS/2, NB platform: user chooses action on document and “application” is found behind the scenes. DO is document.
- results: nice 'create from template' approach, but problems with Save As action (doesn't fit into document model)

4. DataObjects provide
A Lookup – you can query for objects you know about
A Node – to represent it in the UI
A way to have an object that survives file rename/move

5. DataLoader Factory by mime type by extension Context Actions
String actionsContext();
Path to a folder in the system filesystem (layer.xml file)
Can be regular javax.swing.Actions
Can have persistent state
- DataLoader creates DataObject
- developers extends DataLoader, DataLoaders are identified by file extension or better mime type
- DO is extensible using its action context, which is read from layer. So modules can add actions to foreign, third party modules. These actions will appear in right-click menu over DO visual presentation (node)
- extensibility is strong: example – version control system actions added to all source files when specific version control module is installed.

6. FileSystems vs. Loaders API
One type vs. multiple types
One file vs. group of files
Raw data vs. operations on content
Think of a DataObject as representing a (potentially) parsed file
A.java
A.class
B.properties
B_ja.properties
examples of multiple files inside DataObject:
- properties files
- various J2EE files

7. Visualizing DataObjects
NODE!
DataObject.getNodeDelegate()
A DataObject has a...
- DataLoader creates DataObject
- developers extends DataLoader, DataLoaders are identified by file extension or better mime type
- DO is extensible using its action context, which is read from layer. So modules can add actions to foreign, third party modules. These actions will appear in right-click menu over DO visual presentation (node)
- extensibility is strong: example – version control system actions added to all source files when specific version control module is installed.

8. Diagram of API Layers Self explaining, to review API layering
- note that only Nodes are visible in application UI
- note that DO and Node has Lookup context

9. Files, DataObjects, Nodes, Explorer
One set of APIs – but two usages:
1. Visualizing and interacting with real files on disk
2. Visualizing and interacting with parts of NetBeans configuration
Files on disk are a filesystem.
The “system filesystem” is also a filesystem
A registry of configuration information, read/write
Many pieces of UI in NetBeans are just a view of some folder in the System Filesystem
Menus, Toolbars, nodes in the Services tab
There are several predefined DataObjects for convenience of use:
- DataObject: just API, we are making calls if we need something
- MultiDataObject: designed to be extended to create your DO, right class to extend even for representation of one file.
- DataFolder – predefined DO for file folders
- DataShadow – predefined DO for file links
- InstanceDataObject – predefined DO for creating Object instances, used from xml layers a lot

10. DataObject Classes DataObject base API class, default data object
MultiDataObject
abstract support class – may represent >1 file
DataFolder
DataShadow – like a unix symbolic link
InstanceDataObject – represents an object
settings management - .instance files register an object in the system filesystem – different folders have different meanings
There are several predefined DataObjects for convenience of use:
- DataObject: just API, we are making calls if we need something
- MultiDataObject: designed to be extended to create your DO, right class to extend even for representation of one file.
- DataFolder – predefined DO for file folders
- DataShadow – predefined DO for file links
- InstanceDataObject – predefined DO for creating Object instances, used from xml layers a lot

11. Visual Creation /Templates && TemplateWizard
- show wizards and talk about types of DO that are visible (in running NB)
- createFromTemplate is used
- note that from next panel creation is in DO implementor hands (show it on running NB)

12. Templating Languges Any scripting language javax.script.ScriptEngine
Support for Freemarker
substitutions
variables
cycles
CreateFromTemplateAttributeProvider
TemplateWizard.putProperty(xxx) -> ${wizard.xxx}
- scripting can be used inside templates
- support for Freemarker by default, can use others
- AttributeProvider inside global Lookup
- TW.putProperty for passing information from wizard to the script that creates new DO

13. Visual Representation
Represented by Nodes
DataObjects are the model
Nodes are the presentation of the model
They add human-friendly attributes – name, icon, etc.
DataObject.getNodeDelegate()
DataNode - premade superclass
FolderNode & FolderChildren
Write you own hierarchy
projects
files
favorites
- DataObjects are visually represented by Nodes, usually organized into some hierarchies (trees, lists). But Nodes can display anything, not only DataObjects (as we learned in Nodes presentation)
- node for data object can be obtained by getNodeDelegate() call, DataNode is returned in default case, can be overriden in your own DataObjects
- for easier displaying of files, there are prepared FolderNode and FolderChildren, which allows also filtering
- it's possible to write own, specialized hierarchy, example is Projects view in NB IDE.

14. Context of a DataObject
DataObject.getLookup()
added in 6.0 – previously
DataObject.getCookie(Class type) or DataObject.getNodeDelegate().getLookup()
In case of MultiDataObject
getCookieSet().getLookup()
Can be controlled by
getCookieSet().assign(Data.class, data)
- DO.getLookup() is more general version of DO.getCookie(). Allows operation on DO. (open = OpenCookie etc)
- in MultiDO is lookup by default delegated to lookup of CookieSet
- useful action for context modification is assign, which allows to dynamicaly add/override operations on DO

15. Text Editor API for accessing EditorCookie OpenCookie EditCookie
Supporting classes
CloneableEditorSupport
CloneableEditor
DataEditorSupport
Now we take step aside from DataObjects to text editors and their support in NB Platform.
- text editors are connected to DataObjects, usually DataObject has some content which can be shown and edited in text editor
- cookies are API for calling into editors. And cookies are “features”, each cookie offers some feature. I need to open editor, so I do DO.getLookup(OpenCookie.class).open()
- for easier work when I need editor we have supporting classes, CloneableEditor is editor UI (TopComponent), ClonableEditorSupport we usually extend to provide strings for names, save messages etc. We also need to provide CloneableEditorSupport.Env implementation, which specifies input and output streams for data.
DataEditorSupport is support for creating editors for your DataObject, connection between DO and editors

16. Editor APIs Syntax coloring Code folding Navigation Code completion
Brace matching
Actions
Tooltips
Hyperlinks
Indentation
Annotations (e.g. error lines).

17. Schliemann NBS files Simple languages LL(k)
“Real” languages support by the IDE use editor APIs directly

18. Conclusion DataObject logical view over a file created by factories
Extensible via layers
actions
templates
Visualized by Nodes
Content edited by editors

19. DEMO File Type Integration
- do a demo following tutorial at filetype.html
Demo outline:
- create NB module
- create new File type with some experimental mime type (DataObjects, DataLoaders etc. will be created)
- create new action, conditionally enabled and put it into context menu of created DO
- (optional) modify open action on DO to show content in your own TC, not in standard editor (+ talk about visual library that helps with visualizing of content)