TinyPlugz (tiny-plugz 0.3.0 API)

java.lang.Object
- de.skuzzle.tinyplugz.TinyPlugz

```
public abstract class TinyPlugz
extends Object
```
TinyPlugz provides simple runtime classpath extension capabilities by providing a high level API around the java ServiceLoader and URLClassLoader classes. Before usage, TinyPlugz must be configured to specify the plugins which should be loaded. After deploying, TinyPlugz can be accessed like a singleton:
```
 TinyPlugzConfigurator.setup()
         .withProperty("key", value) // some TinyPlugz implementations might
                                     // need additional properties
         .withPlugins(source -> source.addAll(pluginFolder))
         .deploy();

 final Iterator<MyService> providers = TinyPlugz.getInstance()
         .loadServices(MyService.class);
 
```
Usage scenarios

As child Classloader

This is the preferred usage scenario. TinyPlugz will be configured to use the application's Classloader as parent Classloader. The immediate implication is that the host application does not see classes loaded from plugins but plugins see classes of the host application. The only way for the host application to access features of loaded plugins is to use the java service extension feature through the TinyPlugz API.
This method is preferred because it provides a single point of accessing plugin functionality. However, low level access is still possible by using the plugin Classloader directly.
As parent Classloader (container mode)

In this scenario your whole application will be loaded by TinyPlugz, making TinyPlugz the parent Classloader of your application. This is achieved by TinyPlugz calling the main method of your application. This implies that your application can natively access classes from loaded plugins and all loaded plugins can access classes of your application's static class path. For this scenario, your application needs two main methods: One which initializes TinyPlugz and a "real" one which is then called by TinyPlugz in the context of the correct Classloader:
```
 // This is the entry point main method of your application
 public static void main(String[] args) {
     TinyPlugzConfigurator.setup()
             .withProperty("key", value)
             .withPlugins(source -> source.addAll(pluginFolder))
             .deploy()
             .runMain("com.your.domain.ClassWithRealMainMethod", args);
 }
 
```
Please note that this method also replaces the context Classloader of the main thread with TinyPlugz's plugin Classloader.
Deploytime Extensibility

The TinyPlugz instance returned by getInstance() is automatically determined by using java's ServiceLoader class. It will look for an registered service provider for the type TinyPlugz and use the first encountered provider. If no provider is found, the default implementation will be used.
Author:

Simon Taddiken

Constructor Summary

Constructors
Constructor and Description

TinyPlugz()

Constructors
Constructor and Description
`TinyPlugz()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected DelegateClassLoader`	`createClassLoader(PluginSource source, ClassLoader parent)` Creates a `ClassLoader` which accesses the given collection of plugins.
`protected void`	`defaultDispose()` Default behavior for `dispose()`: Calls `close` if the Classloader returned by `getClassLoader()` is an instance of `Closeable`.
`protected <T> Optional<T>`	`defaultGetFirstService(Class<T> type)` Default implementation for `getFirstService(Class)` building upon result of `getServices(Class)`.
`protected Optional<URL>`	`defaultGetResource(String name)` Default implementation for `getResource(String)` building upon result of `getClassLoader()`.
`protected ElementIterator<URL>`	`defaultGetResources(String name)` Default implementation for `getResources(String)` building upon result of `getClassLoader()`.
`protected <T> T`	`defaultGetService(Class<T> type)` Default implementation of `getService(Class)` building upon result of `getServices(Class)`.
`protected void`	`defaultRunMain(String className, String[] args)` Default implementation for `runMain(String, String[])`.
`protected abstract void`	`dispose()` Called upon `undeploy` to release resources.
`protected abstract Iterator<DeployListener>`	`findDeployListeners(ClassLoader pluginClassLoader)` Looks up `DeployListener` to be notified right after this instance has been deployed by the `TinyPlugzConfigurator` class.
`abstract ClassLoader`	`getClassLoader()` Returns the ClassLoader which can access classes from loaded plugins.
`abstract <T> Optional<T>`	`getFirstService(Class<T> type)` Loads services of the given type which are accessible from loaded plugins and the host application by using java's `ServiceLoader` capabilities.
`static TinyPlugz`	`getInstance()` Gets the single TinyPlugz instance.
`abstract Collection<PluginInformation>`	`getPluginInformation()` Gets a collection of information about all loaded plugins.
`abstract Optional<URL>`	`getResource(String name)` Searches for a resource with given name within loaded plugins and the host application.
`abstract ElementIterator<URL>`	`getResources(String name)` Finds all the resources with the given name within loaded plugins and the host application.
`abstract <T> T`	`getService(Class<T> type)` Loads services of the given type which are accessible from loaded plugins and the host application by using java's `ServiceLoader` capabilities.
`abstract <T> ElementIterator<T>`	`getServices(Class<T> type)` Loads all services of the given type which are accessible from loaded plugins and the host application by using java's `ServiceLoader` capabilities.
`protected abstract void`	`initialize(PluginSource source, ClassLoader parentClassLoader, Map<Object,Object> properties)` This method is called by the TinyPlugz runtime right after instantiation of this instance.
`static boolean`	`isDeployed()` Checks whether TinyPlugz is currently deployed and is thus accessible using `getInstance()`.
`boolean`	`isServiceAvailable(Class<?> service)` Checks whether there is at least one provider available for the given service.
`abstract void`	`runMain(String className, String[] args)` Executes a main method in the context of the plugin ClassLoader.
`void`	`undeploy()` Undeploys the global `TinyPlugz` instance and calls its `dispose()` method.

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

- Constructor Detail
  - TinyPlugz
```
public TinyPlugz()
```
- Method Detail
  - getInstance
```
public static TinyPlugz getInstance()
```
    Gets the single TinyPlugz instance.
    
    Returns:
    
    The TinyPlugz instance.
  - isDeployed
```
public static boolean isDeployed()
```
    Checks whether TinyPlugz is currently deployed and is thus accessible using getInstance().
    
    Returns:
    
    Whether TinyPlugz is deployed.
  - undeploy
```
public final void undeploy()
```
    Undeploys the global TinyPlugz instance and calls its dispose() method. This method will fail if the instance on which it is called is not the deployed instance.
  - initialize
```
protected abstract void initialize(PluginSource source,
                                   ClassLoader parentClassLoader,
                                   Map<Object,Object> properties)
```
    This method is called by the TinyPlugz runtime right after instantiation of this instance.
    
    Parameters:
    
    source - The plugins to load.
    
    parentClassLoader - The Classloader to use as parent for the plugin Classloader.
    
    properties - Additional configuration parameters.
    
    Throws:
    
    TinyPlugzException - When initializing failed.
  - findDeployListeners
```
protected abstract Iterator<DeployListener> findDeployListeners(ClassLoader pluginClassLoader)
```
    Looks up DeployListener to be notified right after this instance has been deployed by the TinyPlugzConfigurator class. The listeners are retrieved querying Java's ServiceLoader for the service DeployListener.class.
    
    Parameters:
    
    pluginClassLoader - The ClassLoader for accessing services from plugins.
    
    Returns:
    
    An iterator of available DeployListeners.
  - dispose
```
protected abstract void dispose()
```
    Called upon undeploy to release resources.
  - defaultDispose
```
protected final void defaultDispose()
```
    Default behavior for dispose(): Calls close if the Classloader returned by getClassLoader() is an instance of Closeable.
  - runMain
```
public abstract void runMain(String className,
                             String[] args)
```
    Executes a main method in the context of the plugin ClassLoader. This method uses the plugin ClassLoader to load the class with given className and then searches for a public static void main(String[] args) method to execute. Additionally, the plugin ClassLoader is set as context ClassLoader for the current thread.
    Using this method it is possible to use TinyPlugz as an execution container for the whole application, because all subsequently loaded classes will be loaded by a Classloader which has the plugin Classloader as parent.
    
    Parameters:
    
    className - Name of the class which contains the main method.
    
    args - Arguments to pass to the main method.
    
    Throws:
    
    TinyPlugzException - If loading the class or calling it's main method fails.
  - defaultRunMain
```
protected final void defaultRunMain(String className,
                                    String[] args)
```
    Default implementation for runMain(String, String[]).
    
    Parameters:
    
    className - Name of the class which contains the main method.
    
    args - Arguments to pass to the main method.
    
    Throws:
    
    TinyPlugzException - If loading the class or calling it's main method fails.
  - getPluginInformation
```
public abstract Collection<PluginInformation> getPluginInformation()
```
    Gets a collection of information about all loaded plugins.
    
    Returns:
    
    A read-only collection of plugin information.
  - getClassLoader
```
public abstract ClassLoader getClassLoader()
```
    Returns the ClassLoader which can access classes from loaded plugins. This gives the caller low level access to the plugins. If possible, use the abstractions of the TinyPlugz class instead.
    
    Returns:
    
    The plugin ClassLoader.
  - createClassLoader
```
protected final DelegateClassLoader createClassLoader(PluginSource source,
                                                      ClassLoader parent)
```
    Creates a ClassLoader which accesses the given collection of plugins.
    
    Parameters:
    
    source - The plugins.
    
    parent - The parent ClassLoader.
    
    Returns:
    
    The created ClassLoader.
  - getResource
```
public abstract Optional<URL> getResource(String name)
```
    Searches for a resource with given name within loaded plugins and the host application.
    
    Parameters:
    
    name - Name of the resource.
    
    Returns:
    
    An url to the resource.
  - defaultGetResource
```
protected final Optional<URL> defaultGetResource(String name)
```
    Default implementation for getResource(String) building upon result of getClassLoader().
    
    Parameters:
    
    name - Name of the resource.
    
    Returns:
    
    An url to the resource.
  - getResources
```
public abstract ElementIterator<URL> getResources(String name)
                                           throws IOException
```
    Finds all the resources with the given name within loaded plugins and the host application.
    
    Parameters:
    
    name - The name of the resource.
    
    Returns:
    
    An iterator with resulting resources.
    
    Throws:
    
    IOException - If I/O errors occur.
    
    See Also:
    
    ElementIterator
  - defaultGetResources
```
protected final ElementIterator<URL> defaultGetResources(String name)
                                                  throws IOException
```
    Default implementation for getResources(String) building upon result of getClassLoader().
    
    Parameters:
    
    name - The name of the resource.
    
    Returns:
    
    An iterator with resulting resources.
    
    Throws:
    
    IOException - If I/O errors occur.
  - isServiceAvailable
```
public final boolean isServiceAvailable(Class<?> service)
```
    Checks whether there is at least one provider available for the given service. This method is shorthand for getFirstService(service).isPresent().
    
    Parameters:
    
    service - The service to check for.
    
    Returns:
    
    Whether at least one provider exists.
  - getServices
```
public abstract <T> ElementIterator<T> getServices(Class<T> type)
```
    Loads all services of the given type which are accessible from loaded plugins and the host application by using java's ServiceLoader capabilities.
    
    Type Parameters:
    
    T - The type of the service provider interface.
    
    Parameters:
    
    type - Type of the service to load.
    
    Returns:
    
    An iterator of providers for the requested service.
  - getFirstService
```
public abstract <T> Optional<T> getFirstService(Class<T> type)
```
    Loads services of the given type which are accessible from loaded plugins and the host application by using java's ServiceLoader capabilities. This method only returns the first service or an empty Optional if no provider for the requested service is found.
    
    Type Parameters:
    
    T - The type of the service provider interface.
    
    Parameters:
    
    type - Type of the service to load.
    
    Returns:
    
    The first service which was found.
  - defaultGetFirstService
```
protected final <T> Optional<T> defaultGetFirstService(Class<T> type)
```
    Default implementation for getFirstService(Class) building upon result of getServices(Class).
    
    Type Parameters:
    
    T - The type of the service provider interface.
    
    Parameters:
    
    type - Type of the service to load.
    
    Returns:
    
    The first service which was found.
  - getService
```
public abstract <T> T getService(Class<T> type)
```
    Loads services of the given type which are accessible from loaded plugins and the host application by using java's ServiceLoader capabilities. This method expects that there exists a single provider for the requested service. An exception will be thrown if no provider has been found or if multiple providers have been found.
    
    Type Parameters:
    
    T - The type of the service provider interface.
    
    Parameters:
    
    type - Type of the service to load.
    
    Returns:
    
    The single service.
    
    Throws:
    
    IllegalStateException - If no provider or if more than one provider of given type is available.
  - defaultGetService
```
protected final <T> T defaultGetService(Class<T> type)
```
    Default implementation of getService(Class) building upon result of getServices(Class).
    
    Type Parameters:
    
    T - The type of the service provider interface.
    
    Parameters:
    
    type - Type of the service to load.
    
    Returns:
    
    The single service.
    
    Throws:
    
    IllegalStateException - If no provider or if more than one provider of given type is available.

Class TinyPlugz

Usage scenarios

As child Classloader

As parent Classloader (container mode)

Deploytime Extensibility

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TinyPlugz

Method Detail

getInstance

isDeployed

undeploy

initialize

findDeployListeners

dispose

defaultDispose

runMain

defaultRunMain

getPluginInformation

getClassLoader

createClassLoader

getResource

defaultGetResource

getResources

defaultGetResources

isServiceAvailable

getServices

getFirstService

defaultGetFirstService

getService

defaultGetService