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
|
/*
* Copyright (c) OSGi Alliance (2008, 2009). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.tuscany.sca.osgi.remoteserviceadmin;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import org.osgi.framework.ServiceReference;
/**
* A Remote Service Admin manages the import and export of services.
*
* A Distribution Provider can expose a control interface. This interface allows
* the a remote manager to control the export and import of services.
*
* The API allows a remote manager to export a service, to import a service, and
* find out about the current imports and exports.
*
*
*
* @ThreadSafe
*/
public interface RemoteServiceAdmin {
/**
* Export a service to a given endpoint. The Remote Service Admin must
* create an endpoint from the given description that can be used by other
* Distrbution Providers to connect to this Remote Service Admin and use the
* exported service. This method can return null if the service could not be
* exported because the endpoint could not be implemented by this Remote
* Service Admin.
*
* The properties on a Service Reference are case insensitive while the
* properties on a <code>properties</code> are case sensitive. A value in
* the <code>properties</code> must therefore override any case variant in
* the properties of the Service Reference.
*
* If an endpoint can not be created because no
* {@link EndpointPermission#EXPORT} can be obtained to export this service,
* then this endpoint must be ignored and no Export Registration must be
* included in the returned list.
*
* @param ref The Service Reference to export
* @param properties The properties to create a local endpoint that can be
* implemented by this Remote Service Admin. If this is null, the
* endpoint will be determined by the properties on the service. The
* properties are the same as given for an exported service. They are
* overlaid over any properties the service defines (case
* insensitive). This parameter can be <code>null</code>, this
* should be treated as an empty map.
* @return An Export Registration that combines the Endpoint Description and
* the Service Reference or <code>null</code> if the service could
* not be exported
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*
* TODO discuss case difference in properties
*
* TODO More exceptions?
* TODO Can you export ANY service by providing the proper properties?
*/
List/* <ExportRegistration> */exportService(ServiceReference ref, Map/* <String,Object> */properties)
throws IllegalArgumentException, UnsupportedOperationException;
/**
* Import a service from an endpoint. The Remote Service Admin must use the
* given endpoint to create a proxy. This method can return null if the
* service could not be imported.
*
* TODO if the import reg. is valid (getException==null), can we then assume the
* service is registered?
*
* If an endpoint can not be imported because no
* {@link EndpointPermission#IMPORT} can be obtained, then this endpoint
* must be ignored and no Import Registration must included in the returned
* list.
*
* @param endpoint The Endpoint Description to be used for import
* @return An Import Registration that combines the Endpoint Description and
* the Service Reference or <code>null</code> if the endpoint
* could not be imported
*/
ImportRegistration importService(EndpointDescription endpoint);
/**
* Answer the currently active Export References.
*
* @return A collection of Export Registrations that are currently active.
* @throws SecurityException When the caller no
* {@link EndpointPermission#READ} could be obtained
*/
Collection/* <ExportReference> */getExportedServices();
/**
* Answer the currently active Import References.
*
* @throws SecurityException When the caller no EndpointPermission LIST
* could be obtained
* @return A collection of Import Registrations that are currently active.
* @throws SecurityException When the caller no
* {@link EndpointPermission#READ} could be obtained
*/
Collection/* <ImportReference> */getImportedEndpoints();
}
|
