omero
Class client

java.lang.Object
  extended by 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" More more information, see https://trac.openmicroscopy.org.uk/omero/wiki/ClientDesign

Since:
3.0-Beta3
Author:
Josh Moore, josh at glencoesoftware.com

Constructor Summary
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 #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
 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().
 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()
           
 Ice.Communicator getCommunicator()
          Returns the Communicator for this instance or throws an exception if null.
 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.  
 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 onHearbeat(Runnable runnable)
           
 void onSessionClosed(Runnable runnable)
           
 void onShutdown(Runnable runnable)
           
protected  String parseAndSetInt(Ice.InitializationData data, String key, int newValue)
           
protected  String sess()
          Helper method to access session id
 void setAgent(String agent)
          Sets the user agent string for this client.
 void setInput(String key, omero.RType value)
          Sets an item in the "input" shared (session) memory under the given name.
 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.


client

public client(String host)
Creates an Communicator pointing at the given server using the #DEFAULT_PORT.


client

public client(String host,
              int port)
Creates an Communicator pointing at the given server with the non-standard port.


client

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


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)


client

public client(File... files)
Creates an Communicator from multiple files.


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.

Method Detail

setAgent

public void setAgent(String agent)
Sets the user agent string for this client. Every session creation will be passed this argument. Finding open sesssions with the same agent can be done via ISessionPrx.getMyOpenAgentSessions(String).


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.


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.

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.


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


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.


getServiceFactory

@Deprecated
public omero.api.ServiceFactoryPrx getServiceFactory()
Deprecated. 

See Also:
getSession()

getImplicitContext

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


getProperties

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


getProperty

public String getProperty(String key)
Returns the property value for this key 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().


getPropertyMap

public Map<String,String> getPropertyMap(Ice.Properties properties)
Returns all properties which are prefixed with "omero." or "Ice."


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.PermissionDeniedException
Glacier2.CannotCreateSessionException
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(). 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.

Parameters:
username -
password -
Returns:
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.


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. If no __resources is available currently, one is also created.


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.


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:
IOException
omero.ServerError

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

sess

protected String sess()
               throws omero.ServerError
Helper method to access session id

Throws:
omero.ServerError

onHearbeat

public void onHearbeat(Runnable runnable)

onSessionClosed

public void onSessionClosed(Runnable runnable)

onShutdown

public void onShutdown(Runnable runnable)


OmeroJava Api

Version: Beta4.2.1-r8614-Beta4.2-b41

Copyright © 2009 The University of Dundee. All Rights Reserved.