/
ISession.java
198 lines (172 loc) · 7 KB
/
ISession.java
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
/*
* Copyright 2007 Glencoe Software, Inc. All rights reserved.
* Use is subject to license terms supplied in LICENSE.txt
*/
package ome.api;
import java.util.List;
import java.util.Map;
import java.util.Set;
import ome.annotations.Hidden;
import ome.annotations.NotNull;
import ome.conditions.ApiUsageException;
import ome.conditions.RemovedSessionException;
import ome.conditions.SecurityViolation;
import ome.conditions.SessionTimeoutException;
import ome.model.meta.Session;
import ome.system.Principal;
/**
* <em>Start here</em>: {@link Session} creation service for OMERO. Access to
* all other services is dependent upon a properly created and still active
* {@link Session}.
*
* The {@link Session session's} {@link Session#getUuid() uuid} can be
* considered a capability token, or temporary single use password. Simply by
* possessing it the client has access to all information available to the
* {@link Session}.
*
* Note: Both the RMI {@link ome.system.ServiceFactory} as well as the Ice
* {@code omero.api.ServiceFactoryPrx} use {@link ISession} to acquire a
* {@link Session}. In the RMI case, the {@link ISession} instance is the first
* remote proxy accessed. In the Ice case, Glacier2 contacts {@link ISession}
* itself and returns a ServiceFactory remote proxy. From both ServiceFactory
* instances, it is possible but not necessary to access {@link ISession}.
*
* @author Josh Moore, josh at glencoesoftware.com
* @since 3.0-Beta3
*/
public interface ISession extends ServiceInterface {
/**
* Allows a user to open up another session for him/herself with the given
* defaults without needing to re-enter password.
*/
Session createUserSession(long timeToLiveMilliseconds,
long timeToIdleMillisecond, String defaultGroup);
/**
* Allows an admin to create a {@link Session} for the give
* {@link Principal}
* @param principal
* Non-null {@link Principal} with the target user's name
* @param timeToLiveMilliseconds
* The time that this {@link Session} has until destruction. This
* is useful to override the server default so that an initial
* delay before the user is given the token will not be construed
* as idle time. A value less than 1 will cause the default max
*/
Session createSessionWithTimeout(@NotNull Principal principal,
long timeToLiveMilliseconds);
/**
* Allows an admin to create a {@link Session} for the give
* {@link Principal}
* @param principal
* Non-null {@link Principal} with the target user's name
* @param timeToLiveMilliseconds
* The time that this {@link Session} has until destruction.
* Setting the value to 0 will prevent destruction unless the
* session remains idle.
* @param timeToIdleMilliseconds
* The time that this {@link Session} can remain idle before
* being destroyed. Setting the value to 0 will prevent idleness
*/
Session createSessionWithTimeouts(@NotNull Principal principal,
long timeToLiveMilliseconds, long timeToIdleMilliseconds);
/**
* Creates a new session and returns it to the user.
*
* @throws ApiUsageException
* if principal is null
* @throws SecurityViolation
* if the password check fails
*/
Session createSession(@NotNull Principal principal,
@Hidden String credentials);
/**
* Retrieves the session associated with this uuid, updating the last access
* time as well. Throws a {@link RemovedSessionException} if not present, or
* a {@link SessionTimeoutException} if expired.
*
* This method can be used as a {@link Session} ping.
*/
Session getSession(@NotNull String sessionUuid);
/**
* Retrieves the current reference count for the given uuid. Has the same
* semantics as {@link #getSession(String)}.
*/
int getReferenceCount(@NotNull String sessionUuid);
/**
* Closes session and releases all resources. It is preferred that all
* clients call this method as soon as possible to free memory, but it is
* possible to not call close, and rejoin a session later.
*
* The current reference count for the session is returned. If the session
* does not exist, -1. If this call caused the death of the session, then
* -2.
*/
int closeSession(@NotNull Session session);
// Session listings (ticket:1975)
/**
* Returns a list of open sessions for the current user. The list is ordered
* by session creation time, so that the last item was created last.
*/
List<Session> getMyOpenSessions();
/**
* Like {@link #getMyOpenSessions()} but returns only those sessions
* with the given agent string.
*/
List<Session> getMyOpenAgentSessions(String agent);
/**
* Like {@link #getMyOpenSessions()} but returns only those sessions
* started by official OMERO clients.
*/
List<Session> getMyOpenClientSessions();
// void addNotification(String notification);
// void removeNotification(String notification);
// List<String> listNotifications();
// void defaultNotifications();
// void clearNotifications();
// Session joinSessionByName(@NotNull String sessionName); // Here you don't
// have a
// void disconnectSession(@NotNull Session session);
// void pingSession(@NotNull Session session); // Add to ServiceFactoryI
// Environment contents
// =========================================================================
/**
* Retrieves an entry from the given {@link Session session's} input
* environment.
*/
Object getInput(String session, String key);
/**
* Retrieves all keys in the {@link Session session's} input environment.
*
* @param session
* @return a {@link Set} of keys
*/
Set<String> getInputKeys(String session);
/**
* Retrieves all inputs from the given {@link Session session's} input
* environment.
*/
Map<String, Object> getInputs(String session);
/**
* Places an entry in the given {@link Session session's} input environment.
* If the value is null, the key will be removed.
*/
void setInput(String session, String key, Object objection);
/**
* Retrieves all keys in the {@link Session sesson's} output environment.
*/
Set<String> getOutputKeys(String session);
/**
* Retrieves an entry from the {@link Session session's} output environment.
*/
Object getOutput(String session, String key);
/**
* Retrieves all outputs from the given {@link Session session's} input
* environment.
*/
Map<String, Object> getOutputs(String session);
/**
* Places an entry in the given {@link Session session's} output
* environment. If the value is null, the key will be removed.
*/
void setOutput(String session, String key, Object objection);
}