1 /*
2 Copyright 2011-2014 AGH-UST, http://www.agh.edu.pl
3 Faculty of Computer Science, Electronics and Telecommunications
4 Department of Computer Science
5
6 See the NOTICE file distributed with this work for additional
7 information regarding copyright ownership
8
9 Licensed under the Apache License, Version 2.0 (the "License");
10 you may not use this file except in compliance with the License.
11 You may obtain a copy of the License at
12
13 http://www.apache.org/licenses/LICENSE-2.0
14
15 Unless required by applicable law or agreed to in writing, software
16 distributed under the License is distributed on an "AS IS" BASIS,
17 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 See the License for the specific language governing permissions and
19 limitations under the License.
20 */
21 package org.universAAL.ri.gateway.communicator.service;
22
23 import java.io.InputStream;
24 import java.io.OutputStream;
25 import java.net.URL;
26 import java.util.concurrent.TimeoutException;
27
28 /**
29 * This interface is used by the ImportExportManager for communication with
30 * AALSpace Gateway Communicator via an OSGi service.
31 *
32 * @author skallz
33 *
34 */
35 public interface GatewayCommunicator {
36
37
38 String HASH_KEY = "hash-key";
39
40 /**
41 * System property used for specifying remote AAL Space Gateways addresses
42 * (host ip and port) in comma separated manner. Example: 192.168.192.1:8001,192.168.192.2.8001
43 */
44 String REMOTE_GATEWAYS_PROP = "remote-gateways";
45
46 String LOCAL_SOCKET_PORT = "local-socket-port";
47
48 /**
49 * Property used for specifying bus members that are allowed to be imported into this AAL Space.
50 * List of comma separated regular expressions related to service, context or ui URI.
51 */
52 String IMPORT_SECURITY_CONSTRAINT_ALLOW = "import-security-constraint-allow";
53
54 /**
55 * Property used for specifying bus members that are allowed to be exported to remote AAL Spaces.
56 * List of comma separated regular expressions related to service, context or ui URI.
57 */
58 String EXPORT_SECURITY_CONSTRAINT_ALLOW = "export-security-constraint-allow";
59
60 /**
61 * Property used for specifying bus members that are denied to be imported into this AAL Space.
62 * List of comma separated regular expressions related to service, context or ui URI.
63 */
64 String IMPORT_SECURITY_CONSTRAINT_DENY = "import-security-constraint-deny";
65
66 /**
67 * Property used for specifying bus members that are denied to be exported to remote AAL Spaces.
68 * List of comma separated regular expressions related to service, context or ui URI.
69 */
70 String EXPORT_SECURITY_CONSTRAINT_DENY = "export-security-constraint-deny";
71
72
73 /**
74 * Alias' prefix under which the HTTP servlet will be registered.
75 */
76 String ALIAS_PREFIX = "gateway-communicator";
77
78 /**
79 * Name of the property with which the OSGi service will be registered. Used
80 * to enable two different AALSpace Gateway Communitators in one AALSpace -
81 * mainly for testing purposes.
82 */
83 // String OSGI_ID_PROPERTY = "org.universAAL.ri.id";
84
85 /**
86 * Sends a service request to another AALSpace Gateway Communicator
87 * listening at given URL, waits for the response and returns it.
88 *
89 * Equal to sendServiceRequest(message, to, 0);
90 *
91 * @param message
92 * request massage to be sent to the remote communicator
93 * @param to
94 * remote communicator's URL
95 * @return response message
96 */
97 Message[] sendServiceRequest(Message message, URL[] to);
98
99 Message[] sendServiceRequest(Message message);
100 /**
101 * Sends a service request to another AALSpace Gateway Communicator
102 * listening at given URL, waits for the response and returns it if arrived
103 * before timing out.
104 *
105 * @param message
106 * request massage to be sent to the remote communicator
107 * @param to
108 * remote communicator's URL
109 * @param timeout
110 * time in milliseconds to wait for the response
111 * @return response message
112 * @throws TimeoutException
113 * when timed out
114 */
115 Message[] sendServiceRequest(Message message, URL[] to, long timeout)
116 throws TimeoutException;
117
118 Message[] sendServiceRequest(Message message, long timeout)
119 throws TimeoutException;
120
121 /**
122 * Sends a service request to another AALSpace Gateway Communicator
123 * listening at given URL, registers callback which will be notified once
124 * the response arrives.
125 *
126 * @param message
127 * request massage to be sent to the remote communicator
128 * @param returnTo
129 * local communicator's URL to send back the response to
130 * @param to
131 * remote communicator's URL
132 * @param callback
133 * callback which will be notified once the response arrives
134 */
135 void sendServiceRequestAsync(Message message, URL returnTo, URL to,
136 ResponseCallback callback);
137
138 /**
139 * Sends a context event to other AALSpace Gateway Communicators listening
140 * at given URL.
141 *
142 * @param message
143 * context event to be sent
144 * @param to
145 * a list of URLs of remote communicators to which the event
146 * should be delivered
147 */
148 void sendContextEvent(Message message, URL[] to);
149
150 void sendContextEvent(Message message);
151
152 /**
153 * Sends a ui response to other AALSpace Gateway Communicators listening at
154 * given URL.
155 *
156 * @param message
157 * ui response
158 * @param to
159 * a list of URLs of remote communicators to which the event
160 * should be delivered
161 */
162 void sendUIResponse(Message message, URL[] to);
163
164 void sendUIResponse(Message message);
165
166 /**
167 * Sends a ui request to other AALSpace Gateway Communicators listening at
168 * given URL.
169 *
170 * @param message
171 * ui request
172 * @param to
173 * a list of URLs of remote communicators to which the event
174 * should be delivered
175 */
176 void sendUIRequest(Message message, URL[] to);
177
178 void sendUIRequest(Message message);
179
180 Message[] sendImportRequest(Message message, URL[] to);
181
182 Message sendImportRequest(Message message);
183
184 void sendImportRefresh(Message message, URL[] to);
185
186 void sendImportRefresh(Message message);
187
188 void sendImportRemoval(Message message, URL[] to);
189
190 void sendImportRemoval(Message message);
191
192 void handleMessage(InputStream in, OutputStream out) throws Exception;
193
194 void stop();
195
196 void start() throws Exception;
197 }