Package omero

Class client

  • public class client
extends java.lang.Object
    Central client-side blitz entry point. This class uses solely Ice functionality to provide access to blitz (as opposed to also using Spring) and should be in sync with the OmeroPy omero.client class as well as the OmeroCpp omero::client class. In order to more closely map the destructors in Python and C++, this class keeps a collection of client instances, which are destroyed on program termination. Typical usage: omero.client client = new omero.client(); // Uses ICE_CONFIG omero.client client = new omero.client(host); // Defines "omero.host" omero.client client = new omero.client(host, port); // Defines "omero.host" and "omero.port" For more information, see https://trac.openmicroscopy.org.uk/ome/wiki/ClientDesign
    Since:
    3.0-Beta3

    • Constructor Summary

      Constructors 
      Constructor Description
      client()
      Calls client(Ice.InitializationData) with a new InitializationData
      client​(Ice.InitializationData id)
      Creates an Communicator from a InitializationData instance.
      client​(java.io.File... files)
      Creates an Communicator from multiple files.
      client​(java.lang.String host)
      Creates an Communicator pointing at the given server using the Server.DEFAULT_PORT.
      client​(java.lang.String[] args)
      Calls client(String[], Ice.InitializationData) with a new InitializationData
      client​(java.lang.String[] args, Ice.InitializationData id)
      Creates an Communicator from command-line arguments.
      client​(java.lang.String host, int port)
      Creates an Communicator pointing at the given server with the non-standard port.
      client​(java.util.Map p)
      Creates an Communicator from a Map instance.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void __del__()
      Calls closeSession() and ignores any exceptions.
      void closeSession()
      Closes the session and nulls out the communicator.
      client createClient​(boolean secure)
      Creates a possibly insecure client instance and calls joinSession(String) using the current session id.
      ServiceFactoryPrx createSession()
      Calls createSession(String, String) with null values
      ServiceFactoryPrx createSession​(java.lang.String username, java.lang.String password)
      Performs the actual logic of logging in, which is done via the getRouter(Ice.Communicator).
      void download​(long fileId, java.io.File file)  
      void download​(long fileId, java.io.File file, int blockSize)  
      void enableKeepAlive​(int seconds)
      Resets the "omero.keep_alive" property on the current Communicator which is used on initialization to determine the time-period between checks.
      protected ISessionPrx env()
      Helper method to access session environment
      protected static java.lang.String filesToString​(java.io.File... files)  
      Ice.ObjectAdapter getAdapter()  
      java.lang.String getCategory()
      Returns the category which should be used for all callbacks passed to the server.
      Ice.Communicator getCommunicator()
      Returns the Communicator for this instance or throws an exception if null.
      int getDefaultBlockSize()
      Returns the user-configured setting for "omero.block_size" or DEFAULTBLOCKSIZE if none is set.
      Ice.ImplicitContext getImplicitContext()
      Returns the ImplicitContext which defines what properties will be sent on every method invocation.
      RType getInput​(java.lang.String key)
      Retrieves an item from the "input" shared (session) memory.
      java.util.List<java.lang.String> getInputKeys()
      Returns a list of keys for all items in the "input" shared (session) memory
      RType getOutput​(java.lang.String key)
      Retrieves an item from the "output" shared (session) memory.
      java.util.List<java.lang.String> getOutputKeys()
      Returns a list of keys for all items in the "output" shared (session) memory
      Ice.Properties getProperties()
      Returns the active properties for this instance.
      java.lang.String getProperty​(java.lang.String key)
      Returns the property value for this key or the empty string if none.
      java.util.Map<java.lang.String,​java.lang.String> getPropertyMap()
      Returns all properties which are prefixed with "omero." or "Ice." using the Properties from getProperties().
      java.util.Map<java.lang.String,​java.lang.String> getPropertyMap​(Ice.Properties properties)
      Returns all properties which are prefixed with "omero." or "Ice."
      static Glacier2.RouterPrx getRouter​(Ice.Communicator comm)
      Acquires the default router, and throws an exception if it is not of type {Glacier2.RouterPrx}.
      ServiceFactoryPrx getSession()
      Returns the current active session or throws an exception if none has been created since the last closeSession()
      java.lang.String getSessionId()
      Returns the UUID for the current session without making a remote call.
      java.util.List<StatefulServiceInterfacePrx> getStatefulServices()
      Returns all active StatefulServiceInterface proxies.
      boolean isSecure()
      Specifies whether or not this client was created via a call to createClient(boolean) with a boolean of false.
      ServiceFactoryPrx joinSession​(java.lang.String session)
      Uses the given session uuid as name and password to rejoin a running session.
      int killSession()
      Calls ISession.closeSession(omero.model.Session) until the returned reference count is greater than zero.
      void onHeartbeat​(java.lang.Runnable runnable)  
      void onSessionClosed​(java.lang.Runnable runnable)  
      void onShutdown​(java.lang.Runnable runnable)  
      protected java.lang.String parseAndSetInt​(Ice.InitializationData data, java.lang.String key, int newValue)  
      void setAgent​(java.lang.String agent)
      Sets the user agent string for this client.
      boolean setFastShutdown​(boolean fastShutdown)
      Sets the fastShutdown flag.
      void setInput​(java.lang.String key, RType value)
      Sets an item in the "input" shared (session) memory under the given name.
      void setIP​(java.lang.String ip)
      Sets the user ip string for this client.
      void setOutput​(java.lang.String key, RType value)
      Sets an item in the "output" shared (session) memory under the given name.
      java.lang.String sha1​(java.io.File file)
      Calculates the local sha1 for a file.
      OriginalFile upload​(java.io.File file)  
      OriginalFile upload​(java.io.File file, OriginalFile fileObject)  
      OriginalFile upload​(java.io.File file, OriginalFile fileObject, java.lang.Integer blockSize)
      Utility method to upload a file to the server

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • client

        public client​(Ice.InitializationData id)
        Creates an Communicator from a InitializationData instance. Cannot be null.
        Parameters:
        id - the Ice initialization data

      • client

        public client​(java.lang.String host)
        Creates an Communicator pointing at the given server using the Server.DEFAULT_PORT.
        Parameters:
        host - the server host name

      • client

        public client​(java.lang.String host,
              int port)
        Creates an Communicator pointing at the given server with the non-standard port.
        Parameters:
        host - the server host name
        port - the server port number

      • client

        public client​(java.lang.String[] args,
              Ice.InitializationData id)
        Creates an Communicator from command-line arguments. These are parsed via Ice.Properties.parseIceCommandLineOptions(args) and Ice.Properties.parseCommandLineOptions("omero", args)
        Parameters:
        args - command-line arguments
        id - the Ice initialization data

      • client

        public client​(java.io.File... files)
        Creates an Communicator from multiple files.
        Parameters:
        files - files from which to load properties

      • client

        public client​(java.util.Map p)
        Creates an Communicator from a Map instance. The String representation of each member is added to the Properties under the String representation of the key.
        Parameters:
        p - properties

    • Method Detail

      • setFastShutdown

        public boolean setFastShutdown​(boolean fastShutdown)
        Sets the fastShutdown flag. By setting this to true, you will prevent proper clean up. This should only be used in the case of network loss (or similar).
        Parameters:
        fastShutdown - if shutdown should be fast
        Returns:
        the previous value of this property

      • setAgent

        public void setAgent​(java.lang.String agent)
        Sets the user agent string for this client. Every session creation will be passed this argument. Finding open sessions with the same agent can be done via ISessionPrx.getMyOpenAgentSessions(String).
        Parameters:
        agent - the user agent for sessions

      • setIP

        public void setIP​(java.lang.String ip)
        Sets the user ip string for this client. Every session creation will be passed this argument. Finding open sessions with the same agent can be done via ISessionPrx.getMyOpenAgentSessions(String).
        Parameters:
        ip - the user IP address

      • isSecure

        public boolean isSecure()
        Specifies whether or not this client was created via a call to createClient(boolean) with a boolean of false. If insecure, then all remote calls will use the insecure connection defined by the server.
        Returns:
        if the client's remote calls are secure

      • createClient

        public client createClient​(boolean secure)
                    throws ServerError,
                           Glacier2.CannotCreateSessionException,
                           Glacier2.PermissionDeniedException
        Creates a possibly insecure client instance and calls joinSession(String) using the current session id. If secure is false, then first the "omero.router.insecure" configuration property is retrieved from the server and used as the value of "Ice.Default.Router" for the new client. Any exception thrown during creation is passed on to the caller. Note: detachOnDestroy has NOT been called on the session in the returned client. Clients are responsible for doing this immediately if such desired.
        Throws:
        ServerError
        Glacier2.CannotCreateSessionException
        Glacier2.PermissionDeniedException

      • __del__

        public void __del__()
        Calls closeSession() and ignores any exceptions. Equivalent to OmeroPy's __del__ or OmeroCpp's omero::client::~client()

      • getCommunicator

        public Ice.Communicator getCommunicator()
        Returns the Communicator for this instance or throws an exception if null.
        Returns:
        this client's Communicator

      • getAdapter

        public Ice.ObjectAdapter getAdapter()

      • getSession

        public ServiceFactoryPrx getSession()
        Returns the current active session or throws an exception if none has been created since the last closeSession()
        Returns:
        the current active session

      • getSessionId

        public java.lang.String getSessionId()
        Returns the UUID for the current session without making a remote call. Uses getSession() internally and will throw an exception if no session is active.
        Returns:
        the current session's UUID

      • getCategory

        public java.lang.String getCategory()
        Returns the category which should be used for all callbacks passed to the server.
        Returns:
        the category for callbacks

      • getImplicitContext

        public Ice.ImplicitContext getImplicitContext()
        Returns the ImplicitContext which defines what properties will be sent on every method invocation.
        Returns:
        the ImplicitContext

      • getProperties

        public Ice.Properties getProperties()
        Returns the active properties for this instance.
        Returns:
        the active properties

      • getProperty

        public java.lang.String getProperty​(java.lang.String key)
        Returns the property value for this key or the empty string if none.
        Parameters:
        key - a property key
        Returns:
        the key's value or the empty string if none

      • getPropertyMap

        public java.util.Map<java.lang.String,​java.lang.String> getPropertyMap()
        Returns all properties which are prefixed with "omero." or "Ice." using the Properties from getProperties().
        Returns:
        the "omero." and "Ice." properties

      • getPropertyMap

        public java.util.Map<java.lang.String,​java.lang.String> getPropertyMap​(Ice.Properties properties)
        Returns all properties which are prefixed with "omero." or "Ice."
        Parameters:
        properties - some Ice properties
        Returns:
        the "omero." and "Ice." properties

      • getDefaultBlockSize

        public int getDefaultBlockSize()
        Returns the user-configured setting for "omero.block_size" or DEFAULTBLOCKSIZE if none is set.
        Returns:
        the block size (in bytes)

      • joinSession

        public ServiceFactoryPrx joinSession​(java.lang.String session)
                              throws Glacier2.CannotCreateSessionException,
                                     Glacier2.PermissionDeniedException,
                                     ServerError
        Uses the given session uuid as name and password to rejoin a running session.
        Throws:
        Glacier2.CannotCreateSessionException
        Glacier2.PermissionDeniedException
        ServerError

      • createSession

        public ServiceFactoryPrx createSession​(java.lang.String username,
                                       java.lang.String password)
                                throws Glacier2.CannotCreateSessionException,
                                       Glacier2.PermissionDeniedException,
                                       ServerError
        Performs the actual logic of logging in, which is done via the getRouter(Ice.Communicator). Disallows an extant ServiceFactoryPrx and tries to re-create a null Communicator. A null or empty username will throw an exception, but an empty password is allowed.
        Throws:
        Glacier2.CannotCreateSessionException
        Glacier2.PermissionDeniedException
        ServerError

      • getRouter

        public static Glacier2.RouterPrx getRouter​(Ice.Communicator comm)
        Acquires the default router, and throws an exception if it is not of type {Glacier2.RouterPrx}. Also sets the ImplicitContext on the router proxy.
        Parameters:
        comm - the Ice communicator
        Returns:
        the communicator's router

      • enableKeepAlive

        public void enableKeepAlive​(int seconds)
        Resets the "omero.keep_alive" property on the current Communicator which is used on initialization to determine the time-period between checks.

      • closeSession

        public void closeSession()
        Closes the session and nulls out the communicator. This is required by an Ice bug.
        See Also:
        2370 Ice Ping Error

      • killSession

        public int killSession()
        Calls ISession.closeSession(omero.model.Session) until the returned reference count is greater than zero. The number of invocations is returned. If ISession.closeSession() cannot be called, -1 is returned.

      • sha1

        public java.lang.String sha1​(java.io.File file)
        Calculates the local sha1 for a file.
        Parameters:
        file - a local file
        Returns:
        the file's SHA-1 hexadecimal digest

      • upload

        public OriginalFile upload​(java.io.File file,
                           OriginalFile fileObject,
                           java.lang.Integer blockSize)
                    throws ServerError,
                           java.io.IOException
        Utility method to upload a file to the server
        Parameters:
        file - Cannot be null.
        fileObject - Can be null.
        blockSize - Can be null.
        Throws:
        ServerError
        java.io.IOException

      • download

        public void download​(long fileId,
                     java.io.File file)
              throws ServerError,
                     java.io.IOException
        Throws:
        ServerError
        java.io.IOException

      • download

        public void download​(long fileId,
                     java.io.File file,
                     int blockSize)
              throws ServerError,
                     java.io.IOException
        Throws:
        ServerError
        java.io.IOException

      • getInput

        public RType getInput​(java.lang.String key)
               throws ServerError
        Retrieves an item from the "input" shared (session) memory.
        Throws:
        ServerError

      • getOutput

        public RType getOutput​(java.lang.String key)
                throws ServerError
        Retrieves an item from the "output" shared (session) memory.
        Throws:
        ServerError

      • setInput

        public void setInput​(java.lang.String key,
                     RType value)
              throws ServerError
        Sets an item in the "input" shared (session) memory under the given name.
        Throws:
        ServerError

      • setOutput

        public void setOutput​(java.lang.String key,
                      RType value)
               throws ServerError
        Sets an item in the "output" shared (session) memory under the given name.
        Throws:
        ServerError

      • getInputKeys

        public java.util.List<java.lang.String> getInputKeys()
                                              throws ServerError
        Returns a list of keys for all items in the "input" shared (session) memory
        Throws:
        ServerError

      • getOutputKeys

        public java.util.List<java.lang.String> getOutputKeys()
                                               throws ServerError
        Returns a list of keys for all items in the "output" shared (session) memory
        Throws:
        ServerError

      • parseAndSetInt

        protected java.lang.String parseAndSetInt​(Ice.InitializationData data,
                                          java.lang.String key,
                                          int newValue)

      • filesToString

        protected static java.lang.String filesToString​(java.io.File... files)

      • onHeartbeat

        public void onHeartbeat​(java.lang.Runnable runnable)

      • onSessionClosed

        public void onSessionClosed​(java.lang.Runnable runnable)

      • onShutdown

        public void onShutdown​(java.lang.Runnable runnable)