Interface IProcessManager
-
public interface IProcessManager
Provides instantiating classes within separate process and manages created processes
Before creating any instances within any processes services must be bound to corresponding implementations via
ProcessBinder
andServiceBinder
. Creating any instances within some process is not allowed until binding for this process is not complete (seegetProcessBinder(String)
),ProcessBinder
andServiceBinder
.Note that lifecycle of instance obtained by
getInstance(String, Class)
method is managed by user. You should calldispose(String, Object)
method for instances which will never be used or use instances obtained bygetCloseableInstance(String, Class)
within try-with-resources construction. After disposing, instance could not be used. Instance of service could be created again by the nextgetInstance(String, Class)
calling. If all the instances created within the process are disposed, process will be killed after some delay. This delay could be configured viaProcessBinder.setProcessKillDelay(long)
at the time of binding. By default, it is 1 second.Each separate process will use the same security settings (e.g. security policy) as the main process. Since this, before using this mechanism the 'java.security.policy' system property must be set and these permissions must be granted:
- java.lang.RuntimePermission "shutdownHooks"
- java.lang.RuntimePermission "exitVM.0"
- java.lang.RuntimePermission "createClassLoader"
- java.lang.RuntimePermission "setContextClassLoader"
- java.net.SocketPermission "localhost:0", "listen"
- java.net.SocketPermission "*:1024-", "listen,accept,connect,resolve"
- java.io.FilePermission "<
>", "read,write" - java.lang.RuntimePermission "modifyThread"
- java.util.PropertyPermission "osgi.nls.warnings", "read"
- java.lang.reflect.ReflectPermission "suppressAccessChecks"
" for every library will be loaded or just grant java.lang.RuntimePermission "loadLibrary.*" to load your native libraries. If you need any additional permissions, grant them for your application.Example:
processManager .getProcessBinder("key1") .getServiceBinder(YourService1.class).addLibraries("path/to/your/libv1.so").bindTo(YourService1Impl.class) .getServiceBinder(YourService2.class).bindTo(YourService2Impl.class) .completeBinding() .getProcessBinder("key2") .getServiceBinder(YourService1.class).addLibraries("path/to/your/libv1.so").bindTo(YourService1Impl.class) .completeBinding(); YourService1 instance = processManager.getInstance("key1", YourService1.class); // Do what you want with instance ... processManager.dispose("key1", instance);
- See Also:
ProcessBinder
,ServiceBinder
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
dispose()
Destroys all running processes and release the connections with processesvoid
dispose(String key)
Releases the resources associated with given key, i.e.void
dispose(String key, Object stub)
Releases resources associated with the given key and stub and removes the object running within a separate process associated with that stub from that process.<T> ICloseableInstance<T>
getCloseableInstance(String key, Class<T> service)
Creates an instance by exactly the same asgetInstance(String, Class)
and wraps it intoICloseableInstance
object.InputStream
getErrorsStream(String key)
Returns an input stream piped to the process's with given key standard error stream.InputStream
getInputStream(String key)
Returns an input stream piped to the process's with given key standard output stream.<T> T
getInstance(String key, Class<T> service)
Provides a stub for given service binded to realization instance running within the only one for given key separate processOutputStream
getOutputStream(String key)
Returns an output stream piped to the process's with given key standard input stream.ProcessBinder
getProcessBinder(String key)
Returns new or exiting instance ofProcessBinder
which allows bindings for the process with given key.boolean
isProcessAlive(String key)
Returns if the process with given key is currently running.
-
-
-
Method Detail
-
isProcessAlive
boolean isProcessAlive(String key)
Returns if the process with given key is currently running.
- Parameters:
key
- given key (notnull
)- Returns:
true
if the process with given key is currently runningfalse
otherwise.
-
getProcessBinder
ProcessBinder getProcessBinder(String key)
Returns new or exiting instance of
ProcessBinder
which allows bindings for the process with given key. Each calling for the same key will return the same instance.- Parameters:
key
- given key- Returns:
- new or exiting instance of
ProcessBinder
which allows bindings for the process with given key - See Also:
ProcessBinder
-
getInstance
<T> T getInstance(String key, Class<T> service) throws IllegalAccessException, InstantiationException, IOException, InterruptedException, ProcessStartingTimedOut, ProcessExitedWithErrorException, IllegalStateException
Provides a stub for given service binded to realization instance running within the only one for given key separate process
The given service must be already binded by
bind(String, Class, Class, boolean)
method with given keyNote that lifecycle of instance obtained by this method is managed by user. You should call
release(String, Object)
method for instances which will never be used. This method removes that instance from the separate process associated with the given key and if there are no more instances running within that process, that process will be killed after specified withProcessBinder.setProcessKillDelay(long)
delay and will be created again after the nextgetInstance(String, Class)
call.Also note that the separate process will be created by this method will start with security manager and will use the same security security policy and security properties files as the application process. In addition, these permissions are required by this mechanism to work:
- java.lang.RuntimePermission "shutdownHooks"
- java.lang.RuntimePermission "exitVM.0"
- java.lang.RuntimePermission "createClassLoader"
- java.lang.RuntimePermission "setContextClassLoader"
- java.net.SocketPermission "localhost:0", "listen"
- java.net.SocketPermission "*:1024-", "listen,accept,connect,resolve"
- java.io.FilePermission "<
>", "read,write" - java.lang.RuntimePermission "modifyThread"
- java.util.PropertyPermission "osgi.nls.warnings", "read"
- java.lang.reflect.ReflectPermission "suppressAccessChecks"
" MUST be granted for every library will be loaded or just java.lang.RuntimePermission "loadLibrary.*>" must be granted. Also grant every additional permissions your implementation will use in application security policy. You may use custom security manager or customPolicy
whose are not using policy and properties files. In this case, also set 'java.security.policy' system property with permissions listed above because the separate process will use security manager based on security policy file in 'java.security.policy' system property. If 'java.security.policy' system property is not set,IllegalStateException
will be thrown.- Type Parameters:
T
- - the type of the service- Parameters:
key
- - the key of the process within that to run the implementation (notnull
)service
- - the service for that to return a stub (notnull
)- Returns:
- a stub for given service binded to implementation instance running within a separate process (not
null
) - Throws:
IllegalAccessException
- if could not instantiate the implementation by it's default constructor (for instance, if the default constructor is unaccessible)InstantiationException
- if the implementation represents an abstract class, an interface, an array class, a primitive type, or void; or if the class has no nullary constructor; or if the instantiation fails for some other reasonIOException
- if request of starting a new process or creating an instance within a process is failedInterruptedException
- if request of starting a new process is interruptedProcessStartingTimedOut
- if could not initially start the process, or process does not responseProcessExitedWithErrorException
- if process has not already started, and just after it started, it has exited with error codeIllegalStateException
- if 'java.security.policy' system property is not set (System.getProperty("java.security.policy")
returns null), or service for key is not bound.
-
getCloseableInstance
<T> ICloseableInstance<T> getCloseableInstance(String key, Class<T> service) throws IllegalAccessException, InstantiationException, IOException, InterruptedException, ProcessStartingTimedOut, ProcessExitedWithErrorException, IllegalStateException
Creates an instance by exactly the same as
getInstance(String, Class)
and wraps it intoICloseableInstance
object. The returned object implementsAutoCloseable
and therefore it could be used in "try-with-resources" construction and also just close() method could be called to dispose a wrapped instance from this process manager by exactly the same way asdispose(key, instance)
. The created instance could be obtained byICloseableInstance.getInstance()
method.Look
ICloseableInstance
to see and example of using.This method creates an instance by calling
getInstance(key, service)
, and this instance will be returned byICloseableInstance.getInstance()
method of returned object. TheICloseableInstance.close()
of returned object will invokedispose(key, instance)
All the exceptions declared by this method may be thrown by the same reason as corresponding exceptions declared ingetInstance(String, Class)
method.- Parameters:
key
- a key of a process within that service implementation is runningservice
- a service for that instance is created- Returns:
ICloseableInstance
with wrapped instance created bygetInstance(String, Class)
method andICloseableInstance.close()
which invokesdispose(key, instance)
- Throws:
IllegalAccessException
- if could not instantiate the implementation by it's default constructor (for instance, if the default constructor is unaccessible)InstantiationException
- if the implementation represents an abstract class, an interface, an array class, a primitive type, or void; or if the class has no nullary constructor; or if the instantiation fails for some other reasonIOException
- if request of starting a new process or creating an instance within a process is failedInterruptedException
- if request of starting a new process is interruptedProcessStartingTimedOut
- if could not initially start the process, or process does not responseProcessExitedWithErrorException
- if process has not already started, and just after it started, it has exited with error codeIllegalStateException
- if 'java.security.policy' system property is not set (System.getProperty("java.security.policy")
returns null), or service for key is not bound.- See Also:
ICloseableInstance
-
getOutputStream
OutputStream getOutputStream(String key)
Returns an output stream piped to the process's with given key standard input stream. If process's standard input is redirected to any source other than
If the process with given key has never been running, than this method just returnsProcessBuilder.Redirect.PIPE
(seeProcessBinder.redirectInput(Redirect)
), than this method returns null output stream, for which:null
.- Parameters:
key
- given process's key (notnull
)- Returns:
- an output stream piped to the process's standard input stream,
or null output stream if process's input stream is redirected,
or
null
if process with given key has never been running - See Also:
ProcessBinder.redirectInput(Redirect)
-
getInputStream
InputStream getInputStream(String key)
Returns an input stream piped to the process's with given key standard output stream. If process's standard output is redirected to any destination other than
ProcessBuilder.Redirect.PIPE
(seeProcessBinder.redirectOutput(Redirect)
), this method returns null input stream, for which:- the
read
methods always return-1
- the
available
method always returns0
- the
close
method does nothing
null
.- Parameters:
key
- given process's key (notnull
)- Returns:
- an input stream piped to the process's standard output stream,
or null input stream if porcess's output stream is redirected,
or
null
if process has never been running - See Also:
ProcessBinder.redirectOutput(Redirect)
- the
-
getErrorsStream
InputStream getErrorsStream(String key)
Returns an input stream piped to the process's with given key standard error stream. If process's standard error is redirected to any destination other than
ProcessBuilder.Redirect.PIPE
(seeProcessBinder.redirectError(Redirect)
), or process's errors are merged with ouput (seeProcessBinder.mergeErrorsWithOutput()
) this method returns null input stream, for which:- the
read
methods always return-1
- the
available
method always returns0
- the
close
method does nothing
null
.- Parameters:
key
- given process's key (notnull
)- Returns:
- an input stream piped to the process's standard error stream,
or null input stream if porcess's error stream is redirected,
or
null
if process has never been running - See Also:
ProcessBinder.redirectError(Redirect)
,ProcessBinder.mergeErrorsWithOutput()
- the
-
dispose
void dispose(String key, Object stub)
Releases resources associated with the given key and stub and removes the object running within a separate process associated with that stub from that process. If that process contains no more running instances, it could be killed after implementation - dependent (but could be specified) delay and will be created again after the next
getInstance(String, Class)
calling.- Parameters:
key
- - the specified key for that the object associated with stub is running. (notnull
) Also associated with one remote processstub
- - the stub to release obtained before bygetInstance(String, Class)
method (notnull
)
-
dispose
void dispose(String key)
Releases the resources associated with given key, i.e. kills the process associated with given key. The process for that key could be started again for the next
getInstance(String, Class)
invocation- Parameters:
key
- - the key for that to release resources. This key is also associated with the process to kill. (notnull
)- Throws:
ProcessDestroyingInterruptedException
- when process destroying operation's thread was interrupted
-
dispose
void dispose()
Destroys all running processes and release the connections with processes
- Throws:
ProcessDestroyingInterruptedException
- when some process destroying operation's thread was interrupted
-
-