/
API.ice
291 lines (255 loc) · 12.1 KB
/
API.ice
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
/*
* $Id$
*
* Copyright 2007 Glencoe Software, Inc. All rights reserved.
* Use is subject to license terms supplied in LICENSE.txt
*
*/
#ifndef OMERO_API_ICE
#define OMERO_API_ICE
#include <omero/cmd/API.ice>
#include <omero/ServerErrors.ice>
#include <omero/ModelF.ice>
#include <omero/ServicesF.ice>
#include <omero/System.ice>
#include <omero/Collections.ice>
#include <Glacier2/Session.ice>
#include <Ice/BuiltinSequences.ice>
#include <Ice/Identity.ice>
module omero {
/** The omero::api module defines all the central verbs for working with OMERO.blitz.
*
* <p> Arguments and return values consist of those
* types defined in the other ice files available here. With no
* further custom code, it is possible to interoperate with
* OMERO.blitz simply via the definitions here. Start with the
* ServiceFactory definition at the end of this file.</p>
*
* <p> Note: Using these types is significantly easier in combination with
* the JavaDocs of the OMERO.server, specifically the ome.api
* package. Where not further noted below, the follow mappings between
* ome.api argument types and omero::api argument types hold: </p>
*
* <pre>
* +-----------------------+------------------------+
* | ome.api | omero::api |
* +-----------------------+------------------------+
* |java.lang.Class |string |
* +-----------------------+------------------------+
* |java.util.Set |java.util.List/vector |
* +-----------------------+------------------------+
* |IPojo options (Map) |omero::sys::ParamMap |
* +-----------------------+------------------------+
* |If null needed |omero::RType subclass |
* +-----------------------+------------------------+
* |... |... |
* +-----------------------+------------------------+
* </pre>
**/
module api {
/**
* Primary callback interface for interaction between client and
* server session (""ServiceFactory""). Where possible these methods
* will be called one-way to prevent clients from hanging the server.
**/
["ami"] interface ClientCallback
{
/**
* Heartbeat-request made by the server to guarantee that the client
* is alive. If the client is still active, then some method should
* be made on the server to update the last idle time.
**/
void requestHeartbeat();
/**
* The session to which this ServiceFactory is connected has been
* closed. Almost no further method calls (if any) are possible.
* Create a new session via omero.client.createSession()
**/
void sessionClosed();
/**
* Message that the server will be shutting down in the
* given number of milliseconds, after which all new and
* running method invocations will receive a CancelledException.
**/
void shutdownIn(long milliseconds);
};
/**
* Starting point for all OMERO.blitz interaction.
*
* <p> A ServiceFactory once acquired can be used to create any number
* of service proxies to the server. Most services implement
* {@link ServiceInterface} or its subinterface
* {@link StatefulServiceInterface}. </p>
**/
interface ServiceFactory extends omero::cmd::Session
{
// Security context
/**
* Provides a list of all valid security contexts for this session.
* Each of the returned {@link omero.model.IObject} instances can
* be passed to {@link #setSecurityContext}.
**/
IObjectList getSecurityContexts() throws ServerError;
/**
* Changes the security context for the current session.
*
* <p> A security context limits the set of objects which will
* be returned by all queries and restricts what updates
* can be made. </p>
*
* <p> Current valid values for security context:
* <ul>
* <li>{@link omero.model.ExperimenterGroup} - logs into a
* specific group</li>
* <li>{@link omero.model.Share} - uses IShare to activate a
* share</li>
* </ul> </p>
*
* <p> Passing an unloaded version of either object type will change
* the way the current session operates. Note: only objects which
* are returned by the {@link #getSecurityContexts} method are
* considered valid. Any other instance will cause an exception to
* be thrown. </p>
*
* <h4>Example usage in Python:<h4>
* <pre>
* sf = client.createSession()
* objs = sf.getSecurityContexts()
* old = sf.setSecurityContext(objs\[-1])
* </pre>
*
**/
omero::model::IObject setSecurityContext(omero::model::IObject obj) throws ServerError;
/**
* Re-validates the password for the current session. This prevents
*
* See methods that mention "HasPassword".
**/
void setSecurityPassword(string password) throws ServerError;
// Central OMERO.blitz stateless services.
IAdmin* getAdminService() throws ServerError;
IConfig* getConfigService() throws ServerError;
IContainer* getContainerService() throws ServerError;
ILdap* getLdapService() throws ServerError;
IPixels* getPixelsService() throws ServerError;
IProjection* getProjectionService() throws ServerError;
IQuery* getQueryService() throws ServerError;
IRenderingSettings* getRenderingSettingsService() throws ServerError;
IRepositoryInfo* getRepositoryInfoService() throws ServerError;
IRoi* getRoiService() throws ServerError;
IScript* getScriptService() throws ServerError;
ISession* getSessionService() throws ServerError;
IShare* getShareService() throws ServerError;
ITimeline* getTimelineService() throws ServerError;
ITypes* getTypesService() throws ServerError;
IUpdate* getUpdateService() throws ServerError;
IMetadata* getMetadataService() throws ServerError;
// Central OMERO.blitz stateful services.
Exporter* createExporter() throws ServerError;
JobHandle* createJobHandle() throws ServerError;
RawFileStore* createRawFileStore() throws ServerError;
RawPixelsStore* createRawPixelsStore() throws ServerError;
RenderingEngine* createRenderingEngine() throws ServerError;
Search* createSearchService() throws ServerError;
ThumbnailStore* createThumbnailStore() throws ServerError;
// Shared resources -----------------------------------------------
/**
* Returns a reference to a back-end manager. The
* {@link omero.grid.SharedResources} service provides look ups
* for various facilities offered by OMERO:
* <ul>
* <li><a href="https://docs.openmicroscopy.org/latest/omero/developers/scripts/">OMERO.scripts</a>
* <li><a href="https://docs.openmicroscopy.org/latest/omero/developers/Tables.html">OMERO.tables</a>
* </ul>
* These facilities may or may not be available on first request.
*
* @see omero.grid.SharedResources
**/
omero::grid::SharedResources* sharedResources() throws ServerError;
// General methods ------------------------------------------------
/**
* Allows looking up any stateless service by name.
*
* See Constants.ice for examples of services.
* If a service has been added by third-parties,
* getByName can be used even though no concrete
* method is available.
**/
ServiceInterface* getByName(string name) throws ServerError;
/**
* Allows looking up any stateful service by name.
*
* See Constants.ice for examples of services.
* If a service has been added by third-parties,
* createByName can be used even though no concrete
* method is available.
**/
StatefulServiceInterface* createByName(string name) throws ServerError;
/**
* Subscribe to a given topic. The topic must exist and the user must
* have sufficient permissions for that topic. Further the proxy object
* must match the required type for the topic as encoded in the topic
* name.
**/
void subscribe(string topicName, Object* prx) throws ServerError;
/**
* Sets the single callback used by the ServiceFactory
* to communicate with the client application. A default
* callback is set by the omero::client object on
* session creation which should suffice for most usage.
*
* See the client object's documentation in each language
* mapping for ways to use the callback.
**/
void setCallback(ClientCallback* callback) throws ServerError;
/**
* Marks the session for closure rather than detachment, which will
* be triggered by the destruction of the Glacier2 connection via
* router.destroySession()
*
* Closing the session rather the detaching is more secure, since all
* resources are removed from the server and can safely be set once
* it is clear that a client is finished with those resources.
**/
void closeOnDestroy() throws ServerError;
/**
* Marks the session for detachment rather than closure, which will
* be triggered by the destruction of the Glacier2 connection via
* router.destroySession()
*
* This is the default and allows a lost session to be reconnected,
* at a slight security cost since the session will persist longer
* and can be used by others if the UUID is intercepted.
**/
void detachOnDestroy() throws ServerError;
// Session management
/**
* Returns a list of string ids for currently active services. This will
* _not_ keep services alive, and in fact checks for all expired services
* and removes them.
**/
StringSet activeServices() throws ServerError;
/**
* Requests that the given services be marked as alive. It is
* possible that one of the services has already timed out, in which
* case the returned long value will be non-zero.
*
* Specifically, the bit representing the 0-based index will be 1:
*
* if (retval & 1<<idx == 1<<idx) { // not alive }
*
* Except for fatal server or session errors, this method should never
* throw an exception.
**/
long keepAllAlive(ServiceList proxies) throws ServerError;
/**
* Returns true if the given service is alive.
*
* Except for fatal server or session errors, this method should never
* throw an exception.
**/
bool keepAlive(ServiceInterface* proxy) throws ServerError;
};
};
};
#endif