org.scijava.Gateway Maven / Gradle / Ivy
Show all versions of scijava-common Show documentation
/*
* #%L
* SciJava Common shared library for SciJava software.
* %%
* Copyright (C) 2009 - 2014 Board of Regents of the University of
* Wisconsin-Madison, Broad Institute of MIT and Harvard, and Max Planck
* Institute of Molecular Cell Biology and Genetics.
* %%
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
* #L%
*/
package org.scijava;
import org.scijava.app.App;
import org.scijava.app.AppService;
import org.scijava.app.StatusService;
import org.scijava.command.CommandService;
import org.scijava.console.ConsoleService;
import org.scijava.display.DisplayService;
import org.scijava.event.EventHistory;
import org.scijava.event.EventService;
import org.scijava.input.InputService;
import org.scijava.io.IOService;
import org.scijava.io.RecentFileService;
import org.scijava.log.LogService;
import org.scijava.menu.MenuService;
import org.scijava.module.ModuleService;
import org.scijava.object.ObjectService;
import org.scijava.options.OptionsService;
import org.scijava.platform.AppEventService;
import org.scijava.platform.PlatformService;
import org.scijava.plugin.Plugin;
import org.scijava.plugin.PluginService;
import org.scijava.plugin.RichPlugin;
import org.scijava.script.ScriptService;
import org.scijava.service.Service;
import org.scijava.text.TextService;
import org.scijava.thread.ThreadService;
import org.scijava.tool.IconService;
import org.scijava.tool.ToolService;
import org.scijava.widget.WidgetService;
/**
* Interface for convenience classes that wrap a {@link Context} to provide
* one-line access to a suite of {@link Service}s.
*
* The {@link #get} methods provide consistent {@link Service} instantiation,
* while throwing {@link NoSuchServiceException} if the requested
* {@link Service} is not found.
*
* Sample implementation
*
* Let's say we have a {@code Kraken} service and a {@code Cow} service. Using
* the {@code Context} directly, the code would look like:
*
*
* Context context = new Context();
* context.getService(Cow.class).feedToKraken();
* context.getService(Kraken.class).burp();
*
* To perform these actions, you have to know a priori to ask for a
* {@code Cow} and a {@code Kraken}; i.e., your IDE's code completion will not
* give you a hint. Further, if either service is unavailable, a
* {@link NullPointerException} is thrown.
*
*
* But if we create a {@code Gateway} class called {@code Animals} with the
* following signatures:
*
*
* public Cow cow() { return get(Cow.class); }
* public Kraken kraken() { return get(Kraken.class); }
*
* We can now access our services through the new {@code Animals} gateway:
*
*
* Animals animals = new Animals();
* animals.cow().feedToKraken();
* animals.kraken().burp();
*
* This provides succinct yet explicit access to the {@code Cow} and
* {@code Kraken} services; it is a simple two-layer access to functionality,
* which an IDE can auto-complete. And if one of the services is not available,
* a {@link NoSuchServiceException} is thrown, which facilitates appropriate
* (but optional) handling of missing services.
*
*
* Gateways discoverable at runtime must implement this interface and be
* annotated with @{@link Gateway} with attribute {@link Plugin#type()} =
* {@link Gateway}.class. While it possible to create a gateway merely by
* implementing this interface, it is encouraged to instead extend
* {@link AbstractGateway}, for convenience.
*
*
* @see Context
* @author Mark Hiner
* @author Curtis Rueden
*/
public interface Gateway extends RichPlugin, Versioned {
/**
* Returns an implementation of the requested {@link Service}, if it exists in
* the underlying {@link Context}.
*
* @param serviceClass the requested {@link Service}
* @return The singleton instance of the given class
* @throws NullContextException if the application context is not set.
* @throws NoSuchServiceException if there is no service of the given class.
*/
S get(Class serviceClass);
/**
* Returns an implementation of the {@link Service} with the given class name,
* if it exists in the underlying {@link Context}.
*
* @param serviceClassName name of the requested {@link Service}
* @return The singleton instance of the requested {@link Service}
* @throws NullContextException if the application context is not set.
* @throws NoSuchServiceException if there is no service matching
* {@code serviceClassName}.
*/
Service get(final String serviceClassName);
// -- Gateway methods - services --
AppEventService appEvent();
AppService app();
CommandService command();
ConsoleService console();
DisplayService display();
EventHistory eventHistory();
EventService event();
IconService icon();
InputService input();
IOService io();
LogService log();
MenuService menu();
ModuleService module();
ObjectService object();
OptionsService options();
PlatformService platform();
PluginService plugin();
RecentFileService recentFile();
ScriptService script();
StatusService status();
TextService text();
ThreadService thread();
ToolService tool();
WidgetService widget();
// -- Gateway methods - application --
/** @see org.scijava.app.AppService */
App getApp();
/** @see org.scijava.app.App#getTitle() */
String getTitle();
/** @see org.scijava.app.App#getInfo(boolean) */
String getInfo(boolean mem);
// -- Versioned methods --
/** @see org.scijava.app.App#getVersion() */
@Override
String getVersion();
}