omero

Class client

java.lang.Object

omero.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

Author:

Josh Moore, josh at glencoesoftware.com

Constructor Summary

Constructors

Constructor and Description
client() Calls client(Ice.InitializationData) with a new InitializationData
client(java.io.File... files) Creates an Communicator from multiple files.
client(Ice.InitializationData id) Creates an Communicator from a InitializationData instance.
client(java.util.Map p) Creates an Communicator from a Map instance.
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.

Method Summary

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(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 omero.api.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.
omero.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
omero.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."
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}.
omero.api.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<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(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, omero.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, omero.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.
omero.model.OriginalFile	upload(java.io.File file)
omero.model.OriginalFile	upload(java.io.File file, omero.model.OriginalFile fileObject)
omero.model.OriginalFile	upload(java.io.File file, omero.model.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()

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(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)

Calls client(String[], Ice.InitializationData) with a new InitializationData

Parameters:

args - command-line arguments

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 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 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 omero.api.ServiceFactoryPrx joinSession(java.lang.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(java.lang.String username,
                                                 java.lang.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 java.util.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 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 omero.model.OriginalFile upload(java.io.File file)
                                throws omero.ServerError,
                                       java.io.IOException

Throws:

omero.ServerError

java.io.IOException

upload

public omero.model.OriginalFile upload(java.io.File file,
                                       omero.model.OriginalFile fileObject)
                                throws omero.ServerError,
                                       java.io.IOException

Throws:

omero.ServerError

java.io.IOException

upload

public omero.model.OriginalFile upload(java.io.File file,
                                       omero.model.OriginalFile fileObject,
                                       java.lang.Integer blockSize)
                                throws omero.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:

omero.ServerError

java.io.IOException

download

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

Throws:

omero.ServerError

java.io.IOException

download

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

Throws:

omero.ServerError

java.io.IOException

getInput

public omero.RType getInput(java.lang.String key)
                     throws omero.ServerError

Retrieves an item from the "input" shared (session) memory.

Throws:

omero.ServerError

getOutput

public omero.RType getOutput(java.lang.String key)
                      throws omero.ServerError

Retrieves an item from the "output" shared (session) memory.

Throws:

omero.ServerError

setInput

public void setInput(java.lang.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(java.lang.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 java.util.List<java.lang.String> getInputKeys()
                                              throws omero.ServerError

Returns a list of keys for all items in the "input" shared (session) memory

Throws:

omero.ServerError

getOutputKeys

public java.util.List<java.lang.String> getOutputKeys()
                                               throws omero.ServerError

Returns a list of keys for all items in the "output" shared (session) memory

Throws:

omero.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)

env

protected omero.api.ISessionPrx env()
                             throws omero.ServerError

Helper method to access session environment

Throws:

omero.ServerError

onHeartbeat

public void onHeartbeat(java.lang.Runnable runnable)

onSessionClosed

public void onSessionClosed(java.lang.Runnable runnable)

onShutdown

public void onShutdown(java.lang.Runnable runnable)