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
|
/*******************************************************************************
* Copyright (c) 2004 Composent, Inc. and others. All rights reserved. This
* program and the accompanying materials are made available under the terms of
* the Eclipse Public License v1.0 which accompanies this distribution, and is
* available at http://www.eclipse.org/legal/epl-v10.html
*
* Contributors: Composent, Inc. - initial API and implementation
******************************************************************************/
package org.eclipse.ecf.core.sharedobject;
import java.io.IOException;
import java.util.Map;
import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.ecf.core.ContainerConnectException;
import org.eclipse.ecf.core.IContainer;
import org.eclipse.ecf.core.IOSGIService;
import org.eclipse.ecf.core.identity.ID;
import org.eclipse.ecf.core.identity.Namespace;
import org.eclipse.ecf.core.security.IConnectContext;
import org.eclipse.ecf.core.util.IQueueEnqueue;
/**
* Context reference provided to all ISharedObjects upon initialization.
* Implementers of this interface provide a runtime context for ISharedObject
* instances. Upon initialization within a container (see
* {@link ISharedObject#init(ISharedObjectConfig)}, ISharedObject instances can
* access an instance of this context by calling
* {@link ISharedObjectConfig#getContext()}. They then can have access to the
* functions provided by this context object for use in implementing their
* behavior.
*
* @see ISharedObject#init
* @see ISharedObjectConfig#getContext()
*/
public interface ISharedObjectContext extends IAdaptable {
public boolean isActive();
/**
* Get the local container instance's ID
*
* @return the ID of the enclosing container
*/
public ID getLocalContainerID();
/**
* Get the ISharedObjectManager for this context
*
* @return ISharedObjectManager the shared object manager instance for this
* container. Null if none available.
*/
public ISharedObjectManager getSharedObjectManager();
/**
* Get the IQueueEnqueue instance associated with this ISharedObject. If the
* given container provides a queue for this ISharedObject, this method will
* return a IQueueEnqueue reference to the appropriate queue.
*
* @return IQueueEnqueue instance if an active queue is associated with this
* ISharedObject. If no active queue is associated with the
* ISharedObject, returns null.
*/
public IQueueEnqueue getQueue();
/**
* (non-Javadoc)
*
* @see org.eclipse.ecf.core.IContainer#connect(ID,IConnectContext)
*/
public void connect(ID groupID, IConnectContext connectContext)
throws ContainerConnectException;
/**
* (non-Javadoc)
*
* @see org.eclipse.ecf.core.IContainer#disconnect()
*/
public void disconnect();
/**
* (non-Javadoc)
*
* @see org.eclipse.ecf.core.IContainer#getConnectedID()
*/
public ID getConnectedID();
/**
* (non-Javadoc)
*
* @see org.eclipse.ecf.core.sharedobject.ISharedObjectContainer#isGroupManager()
*/
public boolean isGroupManager();
/**
* (non-Javadoc)
*
* @see org.eclipse.ecf.core.sharedobject.ISharedObjectContainer#getGroupMemberIDs()
*/
public ID[] getGroupMemberIDs();
/**
* Send message to create a remote instance of an ISharedObject with the
* same ID as this instance. This method allows ISharedObject instances
* (with a reference to a valid ISharedObjectContext) to send messages to
* remote containers asking them to create an instance of a new
* ISharedObject. The given ReplicaSharedObjectDescription provides the
* specification of the new object.
*
* @param toContainerID
* the ID of the remote ISharedObjectContainer that is the target
* of the create request. If this parameter is null, the request
* is assumed to be made of <b>all </b> remote containers
* currently in the given group (excepting the local container).
* @param sd
* the ReplicaSharedObjectDescription describing the class, constructor
* and other properties to be associated with the new instance
* @throws IOException
* thrown if message cannot be sent by container
*/
public void sendCreate(ID toContainerID, ReplicaSharedObjectDescription sd)
throws IOException;
/**
* Send create response back to an ISharedObject with the same ID as this
* instance. This method allows ISharedObject instances (with a reference to
* a valid ISharedObjectContext) to send messages to remote containers
* asking them to deliver the create response status back to the
* ISharedObject.
*
* @param toContainerID
* the ID of the container that is to receive this response
* @param throwable
* a throwable associated with the creation. Null means that no
* exception occured
* @param identifier
* the identifier used in the original create message (in the
* shared object description)
* @exception IOException
* thrown if the create response cannot be sent
*/
public void sendCreateResponse(ID toContainerID, Throwable throwable,
long identifier) throws IOException;
/**
* Send message to dispose of a remote instance of the ISharedObject with
* same ID as this instance. This method allows ISharedObject instances to
* control the destruction of remote replicas.
*
* @param toContainerID
* the ID of the remote ISharedObjectContainer that is the target
* of the dispose request. If this parameter is null, the request
* is assumed to be made of <b>all </b> remote containers
* currently in the given group (excepting the local container).
* @throws IOException
* thrown if message cannot be sent by container
*/
public void sendDispose(ID toContainerID) throws IOException;
/**
* Send arbitrary message to remote instance of the ISharedObject with same
* ID as this instance. This method allows ISharedObject instances to send
* arbitrary data to one or more remote replicas of this ISharedObject.
*
* @param toContainerID
* the ID of the remote ISharedObjectContainer that is the target
* container for the message request. If this parameter is null,
* the request is assumed to be made of <b>all </b> remote
* containers currently in the given group (excepting the local
* container).
* @param data
* arbitrary message object. The allowable types of this
* parameter are dependent upon the type of the underlying
* implementing container
* @throws IOException
* thrown if message cannot be sent by container, or if data
* cannot be serialized
*/
public void sendMessage(ID toContainerID, Object data) throws IOException;
/**
* Get a reference to a proxy instance that allows the registration and
* access to local OSGI-platform-provided services. If this method returns
* null, then such services are not available.
*
* @return null if OSGI platform services cannot be accessed, a valid
* instance of the given interface if the context allows access to
* such services
*/
public IOSGIService getServiceAccess();
/**
* Get the Namespace instance that defines the ID type expected by the remote target container
* @return Namespace the namespace by the target for a call to connect(). Null if container
* namespace no longer available
*/
public Namespace getConnectNamespace();
/**
* Get local container properties that it wishes to expose to shared object access
*
* @return Map of properties available to calling shared object. Map returned must not be null.
*/
public Map getLocalContainerProperties();
}
|
