Package com._1c.g5.v8.dt.pm

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 and ServiceBinder. Creating any instances within some process is not allowed until binding for this process is not complete (see getProcessBinder(String)), ProcessBinder and ServiceBinder.

    Note that lifecycle of instance obtained by getInstance(String, Class) method is managed by user. You should call dispose(String, Object) method for instances which will never be used or use instances obtained by getCloseableInstance(String, Class) within try-with-resources construction. After disposing, instance could not be used. Instance of service could be created again by the next getInstance(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 via ProcessBinder.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"
    In addition, you should grant java.lang.RuntimePermission "loadLibrary." 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 Detail

      • isProcessAlive

        boolean isProcessAlive​(String key)

        Returns if the process with given key is currently running.

        Parameters:
        key - given key (not null)
        Returns:
        true if the process with given key is currently running false 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 key

        Note 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 with ProcessBinder.setProcessKillDelay(long) delay and will be created again after the next getInstance(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"
        Since this, 'java.security.policy' system property MUST be set and 'java.security.properties' system property MAY be set. The permissions listed above MUST be granted for your application, and, in addition, java.lang.RuntimePermission "loadLibrary." 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 custom Policy 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 (not null)
        service - - the service for that to return a stub (not null)
        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 reason
        IOException - if request of starting a new process or creating an instance within a process is failed
        InterruptedException - if request of starting a new process is interrupted
        ProcessStartingTimedOut - if could not initially start the process, or process does not response
        ProcessExitedWithErrorException - if process has not already started, and just after it started, it has exited with error code
        IllegalStateException - if 'java.security.policy' system property is not set (System.getProperty("java.security.policy") returns null), or service for key is not bound.

      • 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 ProcessBuilder.Redirect.PIPE (see ProcessBinder.redirectInput(Redirect)), than this method returns null output stream, for which:

        • the write methods always throw IOException
        • the close method does nothing
        If the process with given key has never been running, than this method just returns null.

        Parameters:
        key - given process's key (not null)
        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 (see ProcessBinder.redirectOutput(Redirect)), this method returns null input stream, for which:

        • the read methods always return -1
        • the available method always returns 0
        • the close method does nothing
        If the process with given key has never been running, than this method just returns null.

        Parameters:
        key - given process's key (not null)
        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)

      • 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. (not null) Also associated with one remote process
        stub - - the stub to release obtained before by getInstance(String, Class) method (not null)

      • 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. (not null)
        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