LegacyHooks (ImageJ2 Javadocs 0-SNAPSHOT API)

java.lang.Object
- net.imagej.patcher.LegacyHooks

Direct Known Subclasses:

DefaultLegacyHooks, EssentialLegacyHooks
```
public abstract class LegacyHooks
extends Object
```
Extension points for ImageJ 1.x.
These extension points will be patched into ImageJ 1.x by the CodeHacker. To override the behavior of ImageJ 1.x, a new instance of this class needs to be installed into ij.IJ._hooks.

The essential functionality of the hooks is provided in the EssentialLegacyHooks class, which makes an excellent base class for project-specific implementations.

Author:

Johannes Schindelin

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class LegacyHooks.FatJarNameComparator
Comparator to ensure that problematic fat JARs are sorted last.

Nested Classes
Modifier and Type	Class and Description
`static class`	`LegacyHooks.FatJarNameComparator` Comparator to ensure that problematic fat JARs are sorted last.

Constructor Summary

Constructors
Constructor and Description

LegacyHooks()

Constructors
Constructor and Description
`LegacyHooks()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addMenuItem(String menuPath, String command)` Callback for ImageJ 1.x' menu parsing machinery.
`protected void`	`addPluginClasspath(File file)`
`String[]`	`addPluginDirectory(File directory, String[] names)` Extension point to modify the order in which .jar files are added to the PluginClassLoader.
`InputStream`	`autoGenerateConfigFile(File directory)`
`protected StringBuilder`	`autoGenerateConfigFile(File topLevelDirectory, File directory, String menuPath, String packageName, StringBuilder builder)`
`boolean`	`createInEditor(String fileName, String content)` Extension point to override ImageJ 1.x' editor.
`void`	`debug(String string)` Logs a debug message (to be shown only in debug mode).
`void`	`dispose()` Disposes of the hooks.
`boolean`	`disposing()` Allows interception of ImageJ 1.x's disposal routine while quitting.
`protected void`	`enableIJ1PluginDirs(boolean enable)`
`void`	`error(Throwable t)` Shows an exception.
`String`	`getAppName()` Returns the name to use in place of "ImageJ".
`String`	`getAppVersion()` Returns the version to use in place of the legacy version.
`static Collection<File>`	`getClasspathElements(ClassLoader fromClassLoader, StringBuilder errors, ClassLoader... excludeClassLoaders)` Do not use: for internal use only.
`Object`	`getContext()` Returns the current context, if any.
`URL`	`getIconURL()` Returns the icon to use in place of the ImageJ microscope.
`Map<String,String>`	`getMenuStructure()` Returns ImageJ 1.x' menu structure as a map.
`Iterable<Thread>`	`getThreadAncestors()` Iterates through the current thread's ancestors.
`List<File>`	`handleExtraPluginJars()` Extension point to add to ImageJ 1.x' PluginClassLoader's class path.
`boolean`	`handleNoSuchMethodError(NoSuchMethodError error)` Extension point to enhance ImageJ 1.x' error reporting upon `NoSuchMethodError`.
`void`	`initialized()` First extension point to run just after ImageJ 1.x spun up.
`void`	`installed()` Runs when the hooks are installed into an existing legacy environment.
`boolean`	`interceptCloseAllWindows()` Allows closing additional windows at the end of `WindowManager.closeAllWindows()`.
`Object`	`interceptDragAndDropFile(File f)` Optionally override opening drag-and-dropped files via legacy hooks.
`Object`	`interceptFileOpen(String path)` Optionally override opening resources via legacy hooks.
`void`	`interceptImageWindowClose(Object window)` Hook to ensure `ImageWindow`s are fully cleaned up when they are closed.
`boolean`	`interceptKeyPressed(KeyEvent e)` Intercepts keyboard events sent to ImageJ 1.x.
`Object`	`interceptOpen(String path, int planeIndex, boolean display)` Deprecated. this will be removed before ij1-patcher 1.0.0
`Object`	`interceptOpenImage(String path, int planeIndex)` Optionally override opening images via legacy hooks.
`Object`	`interceptOpenRecent(String path)` Optionally override opening recent images via legacy hooks.
`Object`	`interceptRunPlugIn(String className, String arg)` Intercepts the call to `IJ.runPlugIn(String, String)`.
`boolean`	`isLegacyMode()` Determines whether the image windows should be displayed or not.
`void`	`log(String message)` Logs a message.
`void`	`newPluginClassLoader(ClassLoader loader)` Extension point to run after a new PluginClassLoader was initialized.
`boolean`	`openInEditor(String path)` Extension point to override ImageJ 1.x' editor.
`boolean`	`quit()` Allows interception of ImageJ 1.x's `ImageJ.quit()` method.
`void`	`registerImage(Object image)` Registers an image (possibly not seen before).
`void`	`runAfterRefreshMenus()` Extension point to run after Help>Refresh Menus
`void`	`showProgress(double progress)` Updates the progress bar, where `0 <= progress <= 1.0`.
`void`	`showProgress(int currentIndex, int finalIndex)` Updates the progress bar, where the length of the bar is set to `(currentValue + 1) / finalValue` of the maximum bar length.
`void`	`showStatus(String status)` Shows a status message.
`void`	`unregisterImage(Object image)` Releases an image.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - LegacyHooks
```
public LegacyHooks()
```
- Method Detail
  - isLegacyMode
```
public boolean isLegacyMode()
```
    Determines whether the image windows should be displayed or not.
    
    Returns:
    
    false if ImageJ 1.x should be prevented from opening image windows.
  - getContext
```
public Object getContext()
```
    Returns the current context, if any.
    For ImageJ2-specific hooks, the returned object will be the current SciJava context, or null if the context is not yet initialized.
    
    Returns:
    
    the context, or null
  - quit
```
public boolean quit()
```
    Allows interception of ImageJ 1.x's ImageJ.quit() method.
    
    Returns:
    
    whether ImageJ 1.x should proceed with its usual quitting routine
  - installed
```
public void installed()
```
    Runs when the hooks are installed into an existing legacy environment.
  - dispose
```
public void dispose()
```
    Disposes of the hooks.
    This method is called when ImageJ 1.x is quitting or when new hooks are installed.
  - interceptRunPlugIn
```
public Object interceptRunPlugIn(String className,
                                 String arg)
```
    Intercepts the call to IJ.runPlugIn(String, String).
    
    Parameters:
    
    className - the class name
    
    arg - the argument passed to the runPlugIn method
    
    Returns:
    
    the object to return, or null to let ImageJ 1.x handle the call
  - showProgress
```
public void showProgress(double progress)
```
    Updates the progress bar, where 0 <= progress <= 1.0.
    
    Parameters:
    
    progress - between 0.0 and 1.0
  - showProgress
```
public void showProgress(int currentIndex,
                         int finalIndex)
```
    Updates the progress bar, where the length of the bar is set to (currentValue + 1) / finalValue of the maximum bar length. The bar is erased if currentValue >= finalValue.
    
    Parameters:
    
    currentIndex - the step that was just started
    
    finalIndex - the final step.
  - showStatus
```
public void showStatus(String status)
```
    Shows a status message.
    
    Parameters:
    
    status - the message
  - log
```
public void log(String message)
```
    Logs a message.
    
    Parameters:
    
    message - the message
  - registerImage
```
public void registerImage(Object image)
```
    Registers an image (possibly not seen before).
    
    Parameters:
    
    image - the new image
  - unregisterImage
```
public void unregisterImage(Object image)
```
    Releases an image.
    
    Parameters:
    
    image - the image
  - debug
```
public void debug(String string)
```
    Logs a debug message (to be shown only in debug mode).
    
    Parameters:
    
    string - the debug message
  - error
```
public void error(Throwable t)
```
    Shows an exception.
    
    Parameters:
    
    t - the exception
  - getAppName
```
public String getAppName()
```
    Returns the name to use in place of "ImageJ".
    
    Returns:
    
    the application name
  - getAppVersion
```
public String getAppVersion()
```
    Returns the version to use in place of the legacy version.
    
    Returns:
    
    the application version, or null if we do not override
  - getIconURL
```
public URL getIconURL()
```
    Returns the icon to use in place of the ImageJ microscope.
    
    Returns:
    
    the URL to the icon to use, or null
  - openInEditor
```
public boolean openInEditor(String path)
```
    Extension point to override ImageJ 1.x' editor.
    
    Parameters:
    
    path - the path to the file to open
    
    Returns:
    
    true if the hook opened a different editor
  - createInEditor
```
public boolean createInEditor(String fileName,
                              String content)
```
    Extension point to override ImageJ 1.x' editor.
    
    Parameters:
    
    fileName - the name of the new file
    
    content - the initial content
    
    Returns:
    
    true if the hook opened a different editor
  - enableIJ1PluginDirs
```
protected void enableIJ1PluginDirs(boolean enable)
```
  - addPluginClasspath
```
protected void addPluginClasspath(File file)
```
  - handleExtraPluginJars
```
public List<File> handleExtraPluginJars()
```
    Extension point to add to ImageJ 1.x' PluginClassLoader's class path.
    
    Returns:
    
    a list of class path elements to add
  - runAfterRefreshMenus
```
public void runAfterRefreshMenus()
```
    Extension point to run after Help>Refresh Menus
  - handleNoSuchMethodError
```
public boolean handleNoSuchMethodError(NoSuchMethodError error)
```
    Extension point to enhance ImageJ 1.x' error reporting upon NoSuchMethodError.
    
    Parameters:
    
    error - the exception to handle
    
    Returns:
    
    true if the error was handled by the legacy hook
  - newPluginClassLoader
```
public void newPluginClassLoader(ClassLoader loader)
```
    Extension point to run after a new PluginClassLoader was initialized.
    
    Parameters:
    
    loader - the PluginClassLoader instance
  - addPluginDirectory
```
public String[] addPluginDirectory(File directory,
                                   String[] names)
```
    Extension point to modify the order in which .jar files are added to the PluginClassLoader.
    There is a problem which only strikes large distributions of ImageJ such as Fiji: some .jar files try to be helpful and bundle classes which are actually not theirs, causing problems when newer versions of those .jar files which they shadow are present in the plugins/ or jars/ directory but are not respected by the class loader.
    
    The default hook of this extension point therefore hard-codes a few file names of known offenders (which we politely will call fat .jar files normally) and just pushes them back to the end of the list.
    
    Parameters:
    
    directory - the directory which ImageJ 1.x looked at
    
    names - the list of file names in the order ImageJ 1.x discovered them
    
    Returns:
    
    the ordered, filtered and/or augmented list
  - initialized
```
public void initialized()
```
    First extension point to run just after ImageJ 1.x spun up.
  - autoGenerateConfigFile
```
public InputStream autoGenerateConfigFile(File directory)
```
  - autoGenerateConfigFile
```
protected StringBuilder autoGenerateConfigFile(File topLevelDirectory,
                                               File directory,
                                               String menuPath,
                                               String packageName,
                                               StringBuilder builder)
```
  - addMenuItem
```
public void addMenuItem(String menuPath,
                        String command)
```
    Callback for ImageJ 1.x' menu parsing machinery.
    This method is called whenever ImageJ 1.x adds a command to the menu structure.
    
    Parameters:
    
    menuPath - the menu path of the menu item, or null when reinitializing
    
    command - the command associated with the menu item, or null when reinitializing
  - getMenuStructure
```
public Map<String,String> getMenuStructure()
```
    Returns ImageJ 1.x' menu structure as a map.
    
    Returns:
    
    the menu structure
  - interceptOpen
```
@Deprecated
public Object interceptOpen(String path,
                                        int planeIndex,
                                        boolean display)
```
    Deprecated. this will be removed before ij1-patcher 1.0.0
    
    Optionally override opening resources via legacy hooks.
    This is intended as a "HandleExtraFileTypesPlus".
    
    Parameters:
    
    path - the path to the resource to open, or null if a dialog needs to be shown
    
    planeIndex - If applicable - the index of plane to open or -1 for all planes
    
    display - if true, the opened object should be displayed before returning
    
    Returns:
    
    The opened object, or null to let ImageJ 1.x open the path.
  - interceptFileOpen
```
public Object interceptFileOpen(String path)
```
    Optionally override opening resources via legacy hooks.
    This is intended as a "HandleExtraFileTypesPlus".
    
    Parameters:
    
    path - the path to the resource to open, or null if a dialog needs to be shown
    
    Returns:
    
    The opened object, or null to let ImageJ 1.x open the resource.
  - interceptOpenImage
```
public Object interceptOpenImage(String path,
                                 int planeIndex)
```
    Optionally override opening images via legacy hooks.
    This is intended as a "HandleExtraFileTypesPlus".
    
    Parameters:
    
    path - the path to the image to open, or null if a dialog needs to be shown
    
    planeIndex - If applicable - the index of plane to open or -1 for all planes
    
    Returns:
    
    The opened image, or null to let ImageJ 1.x open the image.
  - interceptOpenRecent
```
public Object interceptOpenRecent(String path)
```
    Optionally override opening recent images via legacy hooks.
    
    Parameters:
    
    path - the path to the recent image to open
    
    Returns:
    
    The opened object, or null to let ImageJ 1.x open the image.
  - interceptDragAndDropFile
```
public Object interceptDragAndDropFile(File f)
```
    Optionally override opening drag-and-dropped files via legacy hooks.
    
    Parameters:
    
    f - the file that was dragged onto the IJ UI
    
    Returns:
    
    The opened object, or null to let ImageJ 1.x open the file as normal.
  - getClasspathElements
```
public static Collection<File> getClasspathElements(ClassLoader fromClassLoader,
                                                    StringBuilder errors,
                                                    ClassLoader... excludeClassLoaders)
```
    Do not use: for internal use only.
  - interceptKeyPressed
```
public boolean interceptKeyPressed(KeyEvent e)
```
    Intercepts keyboard events sent to ImageJ 1.x.
    
    Parameters:
    
    e - the keyboard event
    
    Returns:
    
    whether the event was intercepted
  - getThreadAncestors
```
public Iterable<Thread> getThreadAncestors()
```
    Iterates through the current thread's ancestors.
    ImageJ 1.x' macro options are thread-local. Unfortunately, this does not take into account thread relationships e.g. when threads are spawned in parallel.
    
    By overriding this method, legacy hooks can force ImageJ 1.x to look harder for macro options.
    
    Returns:
    
    the ancestor(s) of the current thread, or null
  - interceptCloseAllWindows
```
public boolean interceptCloseAllWindows()
```
    Allows closing additional windows at the end of WindowManager.closeAllWindows().
    When returning false, ImageJ 1.x will be disallowed from quitting.
    
    Returns:
    
    whether it is okay to quit
  - interceptImageWindowClose
```
public void interceptImageWindowClose(Object window)
```
    Hook to ensure ImageWindows are fully cleaned up when they are closed.
  - disposing
```
public boolean disposing()
```
    Allows interception of ImageJ 1.x's disposal routine while quitting.
    This method is called after it has been confirmed that quitting should proceed. That is, the user OKed all the windows being closed, etc. This method provides one final chance to cancel the quit operation by returning false; otherwise, it performs any needed disposal and cleanup.
    
    Returns:
    
    whether ImageJ 1.x should proceed in quitting
    
    See Also:
    
    which is where ImageJ 1.x actually quits

Class LegacyHooks

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

LegacyHooks

Method Detail

isLegacyMode

getContext

quit

installed

dispose

interceptRunPlugIn

showProgress

showProgress

showStatus

log

registerImage

unregisterImage

debug

error

getAppName

getAppVersion

getIconURL

openInEditor

createInEditor

enableIJ1PluginDirs

addPluginClasspath

handleExtraPluginJars

runAfterRefreshMenus

handleNoSuchMethodError

newPluginClassLoader

addPluginDirectory

initialized

autoGenerateConfigFile

autoGenerateConfigFile

addMenuItem

getMenuStructure

interceptOpen

interceptFileOpen

interceptOpenImage

interceptOpenRecent

interceptDragAndDropFile

getClasspathElements

interceptKeyPressed

getThreadAncestors

interceptCloseAllWindows

interceptImageWindowClose

disposing