client (OMERO API)

java.lang.Object
- omero.client

```
public class client
extends 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 http://trac.openmicroscopy.org.uk/ome/wiki/ClientDesign

Since:

3.0-Beta3

Author:

Josh Moore, josh at glencoesoftware.com

Constructor Summary

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and 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`.
`omero.api.ServiceFactoryPrx`	`createSession()` Calls `createSession(String, String)` with null values
`omero.api.ServiceFactoryPrx`	`createSession(String username, String password)` Performs the actual logic of logging in, which is done via the `getRouter(Ice.Communicator)`.
`void`	`download(long fileId, File file)`
`void`	`download(long fileId, 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 omero.api.ISessionPrx`	`env()` Helper method to access session environment
`protected static String`	`filesToString(File... files)`
`Ice.ObjectAdapter`	`getAdapter()`
`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.
`omero.RType`	`getInput(String key)` Retrieves an item from the "input" shared (session) memory.
`List<String>`	`getInputKeys()` Returns a list of keys for all items in the "input" shared (session) memory
`omero.RType`	`getOutput(String key)` Retrieves an item from the "output" shared (session) memory.
`List<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.
`String`	`getProperty(String key)` Returns the property value for this key or the empty string if none.
`Map<String,String>`	`getPropertyMap()` Returns all properties which are prefixed with "omero." or "Ice."
`Map<String,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}.
`omero.api.ServiceFactoryPrx`	`getServiceFactory()` Deprecated. use `getSession()` instead, to be removed in 5.3
`omero.api.ServiceFactoryPrx`	`getSession()` Returns the current active session or throws an exception if none has been `created` since the last `closeSession()`
`String`	`getSessionId()` Returns the UUID for the current session without making a remote call.
`List<omero.api.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.
`omero.api.ServiceFactoryPrx`	`joinSession(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(Runnable runnable)`
`void`	`onSessionClosed(Runnable runnable)`
`void`	`onShutdown(Runnable runnable)`
`protected String`	`parseAndSetInt(Ice.InitializationData data, String key, int newValue)`
`void`	`setAgent(String agent)` Sets the `user agent` string for this client.
`boolean`	`setFastShutdown(boolean fastShutdown)` Sets the `fastShutdown` flag.
`void`	`setInput(String key, omero.RType value)` Sets an item in the "input" shared (session) memory under the given name.
`void`	`setIP(String ip)` Sets the `user ip` string for this client.
`void`	`setOutput(String key, omero.RType value)` Sets an item in the "output" shared (session) memory under the given name.
`String`	`sha1(File file)` Calculates the local sha1 for a file.
`omero.model.OriginalFile`	`upload(File file)`
`omero.model.OriginalFile`	`upload(File file, omero.model.OriginalFile fileObject)`
`omero.model.OriginalFile`	`upload(File file, omero.model.OriginalFile fileObject, 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()
```
    Calls client(Ice.InitializationData) with a new InitializationData
  - 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(String host)
```
    Creates an Communicator pointing at the given server using the Server.DEFAULT_PORT.
    
    Parameters:
    
    host - the server host name
  - client
```
public client(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(String[] args)
```
    Calls client(String[], Ice.InitializationData) with a new InitializationData
    
    Parameters:
    
    args - command-line arguments
  - client
```
public client(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(File... files)
```
    Creates an Communicator from multiple files.
    
    Parameters:
    
    files - files from which to load properties
  - client
```
public client(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(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(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 omero.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:
    
    omero.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 omero.api.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 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 String getCategory()
```
    Returns the category which should be used for all callbacks passed to the server.
    
    Returns:
    
    the category for callbacks
  - getServiceFactory
```
@Deprecated
public omero.api.ServiceFactoryPrx getServiceFactory()
```
    Deprecated. use getSession() instead, to be removed in 5.3
    
    Returns:
    
    the current active session
    
    See Also:
    
    getSession()
  - 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 String getProperty(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 Map<String,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 Map<String,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 omero.api.ServiceFactoryPrx joinSession(String session)
                                        throws Glacier2.CannotCreateSessionException,
                                               Glacier2.PermissionDeniedException,
                                               omero.ServerError
```
    Uses the given session uuid as name and password to rejoin a running session.
    
    Throws:
    
    Glacier2.CannotCreateSessionException
    
    Glacier2.PermissionDeniedException
    
    omero.ServerError
  - createSession
```
public omero.api.ServiceFactoryPrx createSession()
                                          throws Glacier2.CannotCreateSessionException,
                                                 Glacier2.PermissionDeniedException,
                                                 omero.ServerError
```
    Calls createSession(String, String) with null values
    
    Throws:
    
    Glacier2.CannotCreateSessionException
    
    Glacier2.PermissionDeniedException
    
    omero.ServerError
  - createSession
```
public omero.api.ServiceFactoryPrx createSession(String username,
                                                 String password)
                                          throws Glacier2.CannotCreateSessionException,
                                                 Glacier2.PermissionDeniedException,
                                                 omero.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
    
    omero.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.
  - getStatefulServices
```
public List<omero.api.StatefulServiceInterfacePrx> getStatefulServices()
                                                                throws omero.ServerError
```
    Returns all active StatefulServiceInterface proxies. This can be used to call close before calling setSecurityContext.
    
    Throws:
    
    omero.ServerError
  - 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 String sha1(File file)
```
    Calculates the local sha1 for a file.
    
    Parameters:
    
    file - a local file
    
    Returns:
    
    the file's SHA-1 hexadecimal digest
  - upload
```
public omero.model.OriginalFile upload(File file)
                                throws omero.ServerError,
                                       IOException
```
    Throws:
    
    omero.ServerError
    
    IOException
  - upload
```
public omero.model.OriginalFile upload(File file,
                                       omero.model.OriginalFile fileObject)
                                throws omero.ServerError,
                                       IOException
```
    Throws:
    
    omero.ServerError
    
    IOException
  - upload
```
public omero.model.OriginalFile upload(File file,
                                       omero.model.OriginalFile fileObject,
                                       Integer blockSize)
                                throws omero.ServerError,
                                       IOException
```
    Utility method to upload a file to the server
    
    Parameters:
    
    file - Cannot be null.
    
    fileObject - Can be null.
    
    blockSize - Can be null.
    
    Throws:
    
    omero.ServerError
    
    IOException
  - download
```
public void download(long fileId,
                     File file)
              throws omero.ServerError,
                     IOException
```
    Throws:
    
    omero.ServerError
    
    IOException
  - download
```
public void download(long fileId,
                     File file,
                     int blockSize)
              throws omero.ServerError,
                     IOException
```
    Throws:
    
    omero.ServerError
    
    IOException
  - getInput
```
public omero.RType getInput(String key)
                     throws omero.ServerError
```
    Retrieves an item from the "input" shared (session) memory.
    
    Throws:
    
    omero.ServerError
  - getOutput
```
public omero.RType getOutput(String key)
                      throws omero.ServerError
```
    Retrieves an item from the "output" shared (session) memory.
    
    Throws:
    
    omero.ServerError
  - setInput
```
public void setInput(String key,
                     omero.RType value)
              throws omero.ServerError
```
    Sets an item in the "input" shared (session) memory under the given name.
    
    Throws:
    
    omero.ServerError
  - setOutput
```
public void setOutput(String key,
                      omero.RType value)
               throws omero.ServerError
```
    Sets an item in the "output" shared (session) memory under the given name.
    
    Throws:
    
    omero.ServerError
  - getInputKeys
```
public List<String> getInputKeys()
                          throws omero.ServerError
```
    Returns a list of keys for all items in the "input" shared (session) memory
    
    Throws:
    
    omero.ServerError
  - getOutputKeys
```
public List<String> getOutputKeys()
                           throws omero.ServerError
```
    Returns a list of keys for all items in the "output" shared (session) memory
    
    Throws:
    
    omero.ServerError
  - parseAndSetInt
```
protected String parseAndSetInt(Ice.InitializationData data,
                                String key,
                                int newValue)
```
  - filesToString
```
protected static String filesToString(File... files)
```
  - env
```
protected omero.api.ISessionPrx env()
                             throws omero.ServerError
```
    Helper method to access session environment
    
    Throws:
    
    omero.ServerError
  - onHeartbeat
```
public void onHeartbeat(Runnable runnable)
```
  - onSessionClosed
```
public void onSessionClosed(Runnable runnable)
```
  - onShutdown
```
public void onShutdown(Runnable runnable)
```

Class client

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

client

client

client

client

client

client

client

client

Method Detail

setFastShutdown

setAgent

setIP

isSecure

createClient

__del__

getCommunicator

getAdapter

getSession

getSessionId

getCategory

getServiceFactory

getImplicitContext

getProperties

getProperty

getPropertyMap

getPropertyMap

getDefaultBlockSize

joinSession

createSession

createSession

getRouter

enableKeepAlive

getStatefulServices

closeSession

killSession

sha1

upload

upload

upload

download

download

getInput

getOutput

setInput

setOutput

getInputKeys

getOutputKeys

parseAndSetInt

filesToString

env

onHeartbeat

onSessionClosed

onShutdown

del