* Subclasses of
* The default implementation returns null to indicate that no
* layer reading should be used (use {@link #defaultActions} instead).
*
* {@link javax.swing.JSeparator} instances may be used to separate items.
*
* Suggested context name: Loaders/PRIMARY-FILE/MIME-TYPE/Actions
*
* @return the string name of the context on layer files to read/write actions to
* @since 5.0
*/
protected String actionsContext () {
return null;
}
/**
* Get default actions.
* @deprecated Instead of overriding this method it is preferable to override {@link #actionsContext}.
* @return array of default system actions
*/
@Deprecated
protected SystemAction[] defaultActions () {
SystemAction[] actions = NodeOp.getDefaultActions();
return actions;
}
/** Actions manager.
*/
private final DataLdrActions findManager () {
Object manager = getProperty (ACTION_MANAGER);
if (manager instanceof Class) {
return null;
}
DataLdrActions mgr = (DataLdrActions)manager;
boolean newlyCreated = false;
if (mgr == null) {
String context = actionsContext ();
if (context == null) {
// mark we have no context
putProperty (ACTION_MANAGER, getClass ());
return null;
}
FileObject fo = FileUtil.getConfigFile(context);
if (fo == null) {
fo = FileUtil.getConfigRoot();
try {
fo = FileUtil.createFolder (fo, context);
} catch (IOException ex) {
ERR.log(Level.WARNING, null, ex);
}
newlyCreated = true;
}
mgr = new DataLdrActions (DataFolder.findFolder (fo), this);
if (newlyCreated) {
SystemAction[] arr = defaultActions ();
if (arr != null) {
mgr.setActions (arr);
}
}
putProperty (ACTION_MANAGER, mgr);
}
return mgr;
}
/** Allows the friend code (package and tests) to wait while actions
* are synchronized with the state of disk.
*/
final void waitForActions () {
DataLdrActions mgr = findManager ();
if (mgr != null) {
mgr.waitFinished ();
}
}
/** 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 {@link DataLoaderPool#firstProducerOf}).
* 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 {@link org.openide.actions.ToolsAction service actions}.
* @param actions actions for this loader or
* For example: for files with the same basename but extensions .java and .class, the handler
* should return the same
* The loader can add all files it has recognized into the
* This method is used by {@link DataObject#markFiles}.
*
* @param fo file to mark
* @exception IOException if setting the file's attribute failed
*/
public final void markFile (FileObject fo) throws IOException {
DataLoaderPool.setPreferredLoader(fo, this);
}
/** Writes nothing to the stream.
* @param oo ignored
*/
@Override
public void writeExternal (ObjectOutput oo) throws IOException {
oo.writeObject( new Integer(LOADER_VERSION) );
SystemAction[] arr = (SystemAction[])getProperty (PROP_ACTIONS);
if (arr == null) {
oo.writeObject (null);
} else {
// convert actions to class names
ListDataLoader should be made JavaBeans with
* additional parameters, so a user may configure the loaders in the loader pool.
*
* @author Jaroslav Tulach
*/
public abstract class DataLoader extends SharedClassObject implements DataObject.Factory {
/** error manager for logging the happenings in loaders */
static final Logger ERR = Logger.getLogger("org.openide.loaders.DataLoader"); // NOI18N
// XXX why is this necessary? otherwise reading loader pool now throws heavy
// InvalidClassException's reading (abstract!) DataLoader...? --jglick
private static final long serialVersionUID = 1986614061378346169L;
/** property name of display name */
public static final String PROP_DISPLAY_NAME = "displayName"; // NOI18N
/** property name of list of actions */
public static final String PROP_ACTIONS = "actions"; // NOI18N
/** property name of list of default actions */
private static final String PROP_DEF_ACTIONS = "defaultActions"; // NOI18N
/** key to hold reference to out action manager */
private static final Object ACTION_MANAGER = new Object ();
/** representation class, not public property */
private static final Object PROP_REPRESENTATION_CLASS = new Object ();
/** representation class name, not public property */
private static final Object PROP_REPRESENTATION_CLASS_NAME = new Object ();
private static final int LOADER_VERSION = 1;
/** 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.
*
* @param representationClass the superclass (not necessarily) of all objects
* returned from {@link #findDataObject}. 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.
* @deprecated Use {@link #DataLoader(String)} instead.
*/
@Deprecated
protected DataLoader(Class representationClass) {
putProperty (PROP_REPRESENTATION_CLASS, representationClass);
putProperty (PROP_REPRESENTATION_CLASS_NAME, representationClass.getName());
if (representationClass.getClassLoader() == getClass().getClassLoader()) {
ERR.warning("Use of super(" + representationClass.getName() + ".class) in " + getClass().getName() + "() should be replaced with super(\"" + representationClass.getName() + "\") to reduce unnecessary class loading");
}
}
/** 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
* {@link #findDataObject}.
*
* @param representationClassName the name of the superclass for all objects
* returned from
* {@link #findDataObject}. 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
*/
protected DataLoader( String representationClassName ) {
putProperty (PROP_REPRESENTATION_CLASS_NAME, representationClassName);
// ensure the provided name is correct and can be loaded
assert getRepresentationClass() != null;
}
/**
* Get the representation class for this data loader, as passed to the constructor.
* @return the representation class
*/
public final Class getRepresentationClass() {
Class _cls = (Class) getProperty(PROP_REPRESENTATION_CLASS);
if (_cls != null) {
return _cls.asSubclass(DataObject.class);
}
Class cls;
String clsName = (String)getProperty (PROP_REPRESENTATION_CLASS_NAME);
try {
cls = Class.forName(clsName, false, getClass().getClassLoader()).asSubclass(DataObject.class);
} catch (ClassNotFoundException cnfe) {
throw (IllegalStateException) new IllegalStateException("Failed to load " + clsName + " from " + getClass().getClassLoader()).initCause(cnfe);
}
putProperty (PROP_REPRESENTATION_CLASS, cls);
return cls;
}
/**
* Get the name of the representation class for this data loader.
* Might avoid actually loading the class.
* @return the class name
* @see #getRepresentationClass
* @since 3.25
*/
public final String getRepresentationClassName() {
return (String)getProperty (PROP_REPRESENTATION_CLASS_NAME);
}
/** 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.
*
* @return array of system actions or null if this loader does not have any
* actions
*/
public final SystemAction[] getActions () {
Action[] arr = getSwingActions ();
Listnull if it should not have any
* @see #getActions
*/
public final void setActions (SystemAction[] actions) {
DataLdrActions mgr = findManager ();
if (mgr != null) {
mgr.setActions (actions);
} else {
putProperty (PROP_ACTIONS, actions, true);
}
}
/** Assigns this loader new array of swing actions.
* @param arr ListDataObject.
* recognized
* buffer. Then all these files will be excluded from further processing.
*
* @param fo file object to recognize
* @param recognized recognized file buffer
* @exception DataObjectExistsException if the data object for the
* primary file already exists
* @exception IOException if the object is recognized but cannot be created
* @exception InvalidClassException if the class is not instance of
* {@link #getRepresentationClass}
*
* @return suitable data object or null if the handler cannot
* recognize this object (or its group)
* @see #handleFindDataObject
*/
public final DataObject findDataObject (
FileObject fo, RecognizedFiles recognized
) throws IOException {
try {
return DataObjectPool.handleFindDataObject( this, fo, recognized );
} catch (IOException ioe) {
throw ioe;
} catch (ThreadDeath td) {
throw td;
} catch (RuntimeException e) {
if (e.getClass().getName().startsWith("org.openide.util.lookup")) { // NOI18N
// to propagate
// org.openide.util.lookup.AbstractLookup$ISE: You are trying to modify lookup from lookup query!
throw e;
}
// Some strange error, perhaps an unexpected exception in
// MultiFileLoader.findPrimaryFile. Such an error ought
// not cause whole folder recognizer to die! Assume that
// file/loader is kaput and continue.
IOException ioe = new IOException (e.toString());
Logger.getLogger(DataLoader.class.getName()).log(Level.WARNING, null, e);
ioe.initCause(e);
throw ioe;
}
/*
if (obj != null && !getRepresentationClass ().isInstance (obj)) {
// does not fullfil representation class
throw new java.io.InvalidClassException (obj.getClass ().toString ());
}
return obj;
*/
}
/** Find a data object appropriate to the given file object (as implemented in subclasses).
* @see #findDataObject
* @param fo file object to recognize
* @param recognized recognized file buffer
* @exception DataObjectExistsException as in #findDataObject
* @exception IOException as in #findDataObject
*
* @return the data object or null
*/
protected abstract DataObject handleFindDataObject (
FileObject fo, RecognizedFiles recognized
) 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.
* null if there is no such loader registered
* @see DataLoaderPool#allLoaders
*/
public static null to
// simplify testing whether the file object fo is valid or not
/** Buffer holding a list of primary and secondary files marked as already recognized, to prevent further scanning.
*/
public interface RecognizedFiles {
/** Mark this file as being recognized. It will be excluded
* from further processing.
*
* @param fo file object to exclude
*/
public void markRecognized (FileObject fo);
}
}