netbeans.apache.org/src/content/wiki/DevFaqDataObject.asciidoc

// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= DevFaqDataObject
:jbake-type: wiki
:jbake-tags: wiki, devfaq, needsreview
:jbake-status: published
:keywords: Apache NetBeans wiki DevFaqDataObject
:description: Apache NetBeans wiki DevFaqDataObject
:toc: left
:toc-title:
:syntax: true

=== What is a DataObject?

link:http://bits.netbeans.org/dev/javadoc/org-openide-loaders/index.html?org/openide/loaders/DataObject.html[DataObjects] wrap link:DevFaqFileObject.asciidoc[FileObjects].  (If you do not want to visualize files on disk in an explorer view or create a text editor [with syntax coloring, etc] for files, then you will never need to touch DataObjects.) A FileObject is just a container
for data;  it happens to have a MIME type, but like `java.io.File`, it doesn't know or care what kind
of file it represents, or what data it contains.  DataObject is part of the link:http://www.netbeans.org/download/dev/javadoc/org-openide-loaders/overview-summary.html[Loaders API] - a good overview of this API can be found link:http://www.netbeans.org/download/dev/javadoc/org-openide-loaders/overview-summary.html[here].

A DataObject represents one or more (typically only one) FileObjects. A DataObject knows what kind of a file it represents.  It may represent the parsed contents of a file such as a `.java` file.  Or,
as in the case of link:DevFaqInstanceDataObject.asciidoc[InstanceDataObject], the file _name_ may have semantic meaning.  For example, a file with the name `org-netbeans-modules-speech-SpeakAction.instance` literally is an instruction to "Load the class `org.netbeans.modules.speech.SpeakAction`, and create an instance of it using its default (no argument) constructor"  (this technique is commonly used in the link:DevFaqSystemFilesystem.asciidoc[system filesystem] to register Java objects installed by modules - more about that link:DevFaqFolderOfInstances.asciidoc[here]).

DataObjects are produced by link:DevFaqDataLoader.asciidoc[DataLoaders], which modules register for specific file types.  For each file type, there is (usually) one DataLoader.  For each file of that type, there is one DataObject.

DataObjects are seldom referred to by Java subclass.  If you are casting a DataObject to its implementation class, you are probably doing something wrong.  This is a general rule for which there can be exceptions, but is especially true if you're doing the cast from code in a different module than the one in which the DataObject was defined.  Instead, the usage pattern is to _ask_ a DataObject for instances of interfaces that are the things your code will actually interact with, by calling `DataObject.getLookup().lookup(SomeType.class)` (link:DevFaqLookup.asciidoc[more about Lookup]).

As a simple example, the NetBeans APIs define an interface `org.netbeans.api.actions.Openable`.  It has
one method, `open()`.  That method will open the file in the editor.

What exactly will happen when `open()` is called is entirely up to the module that implements the DataObject and Openable.  The rest of the system does not need to know any of the implementation details - it just needs to know if the DataObject has an Openable.  If it does, then the Open action on its context menu can be enabled, and that action will call
`theDataObject.getLookup().lookup(Openable.class).open()`.

As suggested above, a DataObject may actually represent more than one file - so when you expand a folder
in the UI, there may actually be fewer DataObjects in that folder than there are files.  This is why, in the
NetBeans IDE, a Swing form is represented by a `.java` file and a corresponding `.form`
file, but the `.form` file is not visible in the UI.  `.properties` files have also used
this mechanism to present multiple resource bundles in diverse languages as a single node in the files tree.

However, this ability to represent multiple files with a single DataObject is strongly discouraged for new code and will probably eventually be deprecated - it has serious negative implications for scalability.

=== Related tutorials

* link:http://platform.netbeans.org/tutorials/60/nbm-copyfqn.html[NetBeans Java Language Infrastructure Tutorial]
* link:http://platform.netbeans.org/tutorials/nbm-filetype.html[File Type Integration Tutorial]

=== Apache Migration Information

The content in this page was kindly donated by Oracle Corp. to the
Apache Software Foundation.

This page was exported from link:http://wiki.netbeans.org/DevFaqDataObject[http://wiki.netbeans.org/DevFaqDataObject] , 
that was last modified by NetBeans user Geertjan 
on 2012-01-16T22:44:07Z.


*NOTE:* This document was automatically converted to the AsciiDoc format on 2018-02-07, and needs to be reviewed.