org.openide.loaders

Class DataLoader

java.lang.Object

org.openide.util.SharedClassObject

org.openide.loaders.DataLoader

All Implemented Interfaces:

Externalizable, Serializable, DataObject.Factory

Direct Known Subclasses:

MultiFileLoader

public abstract class DataLoader
extends SharedClassObject
implements DataObject.Factory

A data loader recognizes FileObjects and creates appropriate DataObjects to represent them. The created data object must be a subclass of the representation class provided in the constructor.

Subclasses of DataLoader should be made JavaBeans with additional parameters, so a user may configure the loaders in the loader pool.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	DataLoader.RecognizedFiles Buffer holding a list of primary and secondary files marked as already recognized, to prevent further scanning.

Field Summary

Fields

Modifier and Type	Field and Description
static String	PROP_ACTIONS property name of list of actions
static String	PROP_DISPLAY_NAME property name of display name

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DataLoader(Class<? extends DataObject> representationClass) Deprecated. Use DataLoader.DataLoader(String) instead.
protected	DataLoader(String representationClassName) Create a new data loader.

Method Summary

Modifier and Type	Method and Description
protected String	actionsContext() Identifies the name of context in layer files where the loader wishes to store its own actions and also read them.
protected boolean	clearSharedData()
protected SystemAction[]	defaultActions() Deprecated. Instead of overriding this method it is preferable to override DataLoader.actionsContext().
protected String	defaultDisplayName() Get the default display name of this loader.
DataObject	findDataObject(FileObject fo, DataLoader.RecognizedFiles recognized) Find a data object appropriate to the given file object--the meat of this class.
DataObject	findDataObject(FileObject fo, Set<? super FileObject> recognized) Find a data object appropriate to the given file object--the meat of this class.
SystemAction[]	getActions() Get actions.
String	getDisplayName() Get the current display name of this loader.
static <T extends DataLoader> T	getLoader(Class<T> loaderClass) Get a registered loader from the pool.
Class<? extends DataObject>	getRepresentationClass() Get the representation class for this data loader, as passed to the constructor.
String	getRepresentationClassName() Get the name of the representation class for this data loader.
protected abstract DataObject	handleFindDataObject(FileObject fo, DataLoader.RecognizedFiles recognized) Find a data object appropriate to the given file object (as implemented in subclasses).
void	markFile(FileObject fo) Utility method to mark a file as belonging to this loader.
void	readExternal(ObjectInput oi) Reads actions and display name from the stream.
void	setActions(SystemAction[] actions) Set actions.
protected void	setDisplayName(String displayName) Set the display name for this loader.
void	writeExternal(ObjectOutput oo) Writes nothing to the stream.

Methods inherited from class org.openide.util.SharedClassObject

addNotify, addPropertyChangeListener, equals, finalize, findObject, findObject, firePropertyChange, getLock, getProperty, hashCode, initialize, putProperty, putProperty, removeNotify, removePropertyChangeListener, reset, writeReplace

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROP_DISPLAY_NAME

public static final String PROP_DISPLAY_NAME

property name of display name

See Also:

Constant Field Values

PROP_ACTIONS

public static final String PROP_ACTIONS

property name of list of actions

See Also:

Constant Field Values

Constructor Detail

DataLoader

@Deprecated
protected DataLoader(Class<? extends DataObject> representationClass)

Deprecated. Use DataLoader.DataLoader(String) instead.

Create a new data loader. Pass its representation class as a parameter to the constructor. It is recommended that representation class is superclass of all DataObjects produced by the loaded, but it is not required any more.

Parameters:

representationClass - the superclass (not necessarily) of all objects returned from DataLoader.findDataObject(org.openide.filesystems.FileObject, java.util.Set<? super org.openide.filesystems.FileObject>). The class may be anything but should be chosen to be as close as possible to the actual class of objects returned from the loader, to best identify the loader's data objects to listeners.

DataLoader

protected DataLoader(String representationClassName)

Create a new data loader. Pass its representation class name as a parameter to the constructor. The constructor is then allowed to return only subclasses of the representation class as the result of DataLoader.findDataObject(org.openide.filesystems.FileObject, java.util.Set<? super org.openide.filesystems.FileObject>).

Parameters:

representationClassName - the name of the superclass for all objects returned from DataLoader.findDataObject(org.openide.filesystems.FileObject, java.util.Set<? super org.openide.filesystems.FileObject>). The class may be anything but should be chosen to be as close as possible to the actual class of objects returned from the loader, to best identify the loader's data objects to listeners.

Since:

1.10

Method Detail

getRepresentationClass

public final Class<? extends DataObject> getRepresentationClass()

Get the representation class for this data loader, as passed to the constructor.

Returns:

the representation class

getRepresentationClassName

public final String getRepresentationClassName()

Get the name of the representation class for this data loader. Might avoid actually loading the class.

Returns:

the class name

Since:

3.25

See Also:

DataLoader.getRepresentationClass()

getActions

public final SystemAction[] getActions()

Get actions. These actions are used to compose a popup menu for the data object. Also these actions should be customizable by the user, so he can modify the popup menu on a data object.

Returns:

array of system actions or null if this loader does not have any actions

actionsContext

protected String actionsContext()

Identifies the name of context in layer files where the loader wishes to store its own actions and also read them. In principle any Action instance can be registered in the context and it will be visible in the default DataNode for data object created by this loader. Only SystemAction can however be manipulated from DataLoader getActions/setActions methods.

The default implementation returns null to indicate that no layer reading should be used (use DataLoader.defaultActions() instead).

JSeparator instances may be used to separate items.

Suggested context name: Loaders/PRIMARY-FILE/MIME-TYPE/Actions

Returns:

the string name of the context on layer files to read/write actions to

Since:

5.0

defaultActions

@Deprecated
protected SystemAction[] defaultActions()

Deprecated. Instead of overriding this method it is preferable to override DataLoader.actionsContext().

Get default actions.

Returns:

array of default system actions

setActions

public final void setActions(SystemAction[] actions)

Set actions.

Note that this method is public, not protected, so it is possible for anyone to modify the loader's popup actions externally (after finding the loader using DataLoaderPool.firstProducerOf(java.lang.Class<? extends org.openide.loaders.DataObject>)). While this is possible, anyone doing so must take care to place new actions into sensible positions, including consideration of separators. This may also adversely affect the intended feel of the data objects. A preferable solution is generally to use service actions.

Parameters:

actions - actions for this loader or null if it should not have any

See Also:

DataLoader.getActions()

getDisplayName

public final String getDisplayName()

Get the current display name of this loader.

Returns:

display name

setDisplayName

protected final void setDisplayName(String displayName)

Set the display name for this loader. Only subclasses should set the name.

Parameters:

displayName - new name

defaultDisplayName

protected String defaultDisplayName()

Get the default display name of this loader.

Returns:

default display name

findDataObject

public final DataObject findDataObject(FileObject fo,
                                       Set<? super FileObject> recognized)
                                throws IOException

Find a data object appropriate to the given file object--the meat of this class.

Specified by:

findDataObject in interface DataObject.Factory

Parameters:

fo - file object

recognized - set of already processed files

Returns:

created data object

Throws:

IOException

DataObjectExistsException - if the data object for the primary file already exists

InvalidClassException - if the class is not instance of DataLoader.getRepresentationClass()

Since:

7.0

See Also:

DataLoader

findDataObject

public final DataObject findDataObject(FileObject fo,
                                       DataLoader.RecognizedFiles recognized)
                                throws IOException

Find a data object appropriate to the given file object--the meat of this class.

For example: for files with the same basename but extensions .java and .class, the handler should return the same DataObject.

The loader can add all files it has recognized into the recognized buffer. Then all these files will be excluded from further processing.

Parameters:

fo - file object to recognize

recognized - recognized file buffer

Returns:

suitable data object or null if the handler cannot recognize this object (or its group)

Throws:

DataObjectExistsException - if the data object for the primary file already exists

IOException - if the object is recognized but cannot be created

InvalidClassException - if the class is not instance of DataLoader.getRepresentationClass()

See Also:

DataLoader.handleFindDataObject(org.openide.filesystems.FileObject, org.openide.loaders.DataLoader.RecognizedFiles)

handleFindDataObject

protected abstract DataObject handleFindDataObject(FileObject fo,
                                                   DataLoader.RecognizedFiles recognized)
                                            throws IOException

Find a data object appropriate to the given file object (as implemented in subclasses).

Parameters:

fo - file object to recognize

recognized - recognized file buffer

Returns:

the data object or null

Throws:

DataObjectExistsException - as in #findDataObject

IOException - as in #findDataObject

See Also:

DataLoader.findDataObject(org.openide.filesystems.FileObject, java.util.Set<? super org.openide.filesystems.FileObject>)

markFile

public final void markFile(FileObject fo)
                    throws IOException

Utility method to mark a file as belonging to this loader. When the file is to be recognized this loader will be used first.

This method is used by DataObject.markFiles().

Parameters:

fo - file to mark

Throws:

IOException - if setting the file's attribute failed

writeExternal

public void writeExternal(ObjectOutput oo)
                   throws IOException

Writes nothing to the stream.

Specified by:

writeExternal in interface Externalizable

Overrides:

writeExternal in class SharedClassObject

Parameters:

oo - ignored

Throws:

IOException

readExternal

public void readExternal(ObjectInput oi)
                  throws IOException,
                         ClassNotFoundException

Reads actions and display name from the stream.

Specified by:

readExternal in interface Externalizable

Overrides:

readExternal in class SharedClassObject

Parameters:

oi - input source to read from

Throws:

SafeException - if some of the actions is not found in the stream, but all the content has been read ok. Subclasses can catch this exception and continue reading from the stream

IOException

ClassNotFoundException

clearSharedData

protected boolean clearSharedData()

Overrides:

clearSharedData in class SharedClassObject

getLoader

public static <T extends DataLoader> T getLoader(Class<T> loaderClass)

Get a registered loader from the pool.

Parameters:

loaderClass - exact class of the loader (not its data object representation class)

Returns:

the loader instance, or null if there is no such loader registered

See Also:

DataLoaderPool.allLoaders()