1 /*
2 ServiceType.java
3
4 (C) Copyright IBM Corp. 2005, 2009
5
6 THIS FILE IS PROVIDED UNDER THE TERMS OF THE ECLIPSE PUBLIC LICENSE
7 ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS FILE
8 CONSTITUTES RECIPIENTS ACCEPTANCE OF THE AGREEMENT.
9
10 You can obtain a current copy of the Eclipse Public License from
11 http://www.opensource.org/licenses/eclipse-1.0.php
12
13 @author : Roberto Pineiro, IBM, roberto.pineiro@us.ibm.com
14 * @author : Chung-hao Tan, IBM, chungtan@us.ibm.com
15 *
16 * Change History
17 * Flag Date Prog Description
18 *-------------------------------------------------------------------------------
19 * 1516246 2006-07-22 lupusalex Integrate SLP client code
20 * 1804402 2007-09-28 ebak IPv6 ready SLP
21 * 2003590 2008-06-30 blaschke-oss Change licensing from CPL to EPL
22 * 2524131 2009-01-21 raman_arora Upgrade client to JDK 1.5 (Phase 1)
23 * 2531371 2009-02-10 raman_arora Upgrade client to JDK 1.5 (Phase 2)
24 */
25
26 package org.metricshub.wbem.sblim.slp;
27
28 /*-
29 * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
30 * WBEM Java Client
31 * ჻჻჻჻჻჻
32 * Copyright 2023 - 2025 MetricsHub
33 * ჻჻჻჻჻჻
34 * Licensed under the Apache License, Version 2.0 (the "License");
35 * you may not use this file except in compliance with the License.
36 * You may obtain a copy of the License at
37 *
38 * http://www.apache.org/licenses/LICENSE-2.0
39 *
40 * Unless required by applicable law or agreed to in writing, software
41 * distributed under the License is distributed on an "AS IS" BASIS,
42 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
43 * See the License for the specific language governing permissions and
44 * limitations under the License.
45 * ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱
46 */
47
48 import java.net.InetAddress;
49 import java.util.Locale;
50 import java.util.Vector;
51
52 /**
53 * The Locator is the UA interface, allowing clients to query the SLP framework
54 * about existing service types, services instances, and about the attributes of
55 * an existing service instance or service type. Queries for services and
56 * attributes are made in the locale with which the Locator was created, queries
57 * for service types are independent of locale.
58 */
59 public interface Locator {
60 /**
61 * Return the language locale with which this object was created.
62 *
63 * @return The locale
64 */
65 public abstract Locale getLocale();
66
67 /**
68 * Returns an enumeration of ServiceType objects giving known service types
69 * for the given scopes and given naming authority. If no service types are
70 * found, an empty enumeration is returned.
71 *
72 * @param pNamingAuthority
73 * The naming authority. Use "" for the default naming authority
74 * and "*" for all naming authorities.
75 * @param pScopes
76 * A Vector of scope names. The vector should be selected from
77 * the results of a findScopes() API invocation. Use "DEFAULT"
78 * for the default scope.
79 * @return The enumeration
80 * @throws ServiceLocationException
81 */
82 public abstract ServiceLocationEnumeration findServiceTypes(String pNamingAuthority, Vector<String> pScopes)
83 throws ServiceLocationException;
84
85 /**
86 * Returns an enumeration of ServiceType objects giving known service types
87 * for the given scopes and given naming authority. If no service types are
88 * found, an empty enumeration is returned. <br />
89 * <br />
90 * <em>This method is not part of the RFC 2614 interface definition.</em>
91 *
92 * @param pNamingAuthority
93 * The naming authority. Use "" for the default naming authority
94 * and "*" for all naming authorities.
95 * @param pScopes
96 * A Vector of scope names. The vector should be selected from
97 * the results of a findScopes() API invocation. Use "DEFAULT"
98 * for the default scope.
99 * @param pDirectoryAgent
100 * A vector of InetAddress that specify the directory agents to
101 * look for.
102 *
103 * @return The enumeration
104 * @throws ServiceLocationException
105 */
106 public abstract ServiceLocationEnumeration findServiceTypes(
107 String pNamingAuthority,
108 Vector<String> pScopes,
109 Vector<InetAddress> pDirectoryAgent
110 )
111 throws ServiceLocationException;
112
113 /**
114 * Returns a vector of ServiceURL objects for services matching the query,
115 * and having a matching type in the given scopes. If no services are found,
116 * an empty enumeration is returned.
117 *
118 * @param pType
119 * The SLP service type of the service.
120 * @param pScopes
121 * A Vector of scope names. The vector should be selected from
122 * the results of a findScopes() API invocation. Use "DEFAULT"
123 * for the default scope.
124 * @param pSearchFilter
125 * An LDAPv3 [4] string encoded query. If the filter is empty,
126 * i.e. "", all services of the requested type in the specified
127 * scopes are returned. SLP reserved characters must be escaped
128 * in the query. Use ServiceLocationAttribute.escapeId() and
129 * ServiceLocationAttribute.escapeValue() to construct the query.
130 *
131 * @return The enumeration
132 * @throws ServiceLocationException
133 */
134 public abstract ServiceLocationEnumeration findServices(
135 ServiceType pType,
136 Vector<String> pScopes,
137 String pSearchFilter
138 )
139 throws ServiceLocationException;
140
141 /**
142 * Returns a vector of ServiceURL objects for services matching the query,
143 * and having a matching type in the given scopes. If no services are found,
144 * an empty enumeration is returned. <br />
145 * <br />
146 * <em>This method is not part of the RFC 2614 interface definition.</em>
147 *
148 * @param pType
149 * The SLP service type of the service.
150 * @param pScopes
151 * A Vector of scope names. The vector should be selected from
152 * the results of a findScopes() API invocation. Use "DEFAULT"
153 * for the default scope.
154 * @param pSearchFilter
155 * An LDAPv3 [4] string encoded query. If the filter is empty,
156 * i.e. "", all services of the requested type in the specified
157 * scopes are returned. SLP reserved characters must be escaped
158 * in the query. Use ServiceLocationAttribute.escapeId() and
159 * ServiceLocationAttribute.escapeValue() to construct the query.
160 * @param pDirectoryAgents
161 * A vector of InetAddress that specify the directory agents to
162 * look for.
163 *
164 * @return The enumeration
165 * @throws ServiceLocationException
166 */
167 public abstract ServiceLocationEnumeration findServices(
168 ServiceType pType,
169 Vector<String> pScopes,
170 String pSearchFilter,
171 Vector<InetAddress> pDirectoryAgents
172 )
173 throws ServiceLocationException;
174
175 /**
176 * For the URL and scope, return a Vector of ServiceLocationAttribute
177 * objects whose ids match the String patterns in the attributeIds Vector.
178 * The request is made in the language locale of the Locator. If no
179 * attributes match, an empty enumeration is returned.
180 *
181 * @param URL
182 * The URL for which the attributes are desired.
183 * @param scopes
184 * A Vector of scope names. The vector should be selected from
185 * the results of a findScopes() API invocation. Use "DEFAULT"
186 * for the default scope.
187 * @param attributeIds
188 * A Vector of String patterns identifying the desired
189 * attributes. An empty vector means return all attributes. As
190 * described in [7], the patterns may include wildcard to match
191 * substrings. The strings may include SLP reserved characters,
192 * they will be escaped by the API before transmission.
193 * @return The enumeration
194 * @throws ServiceLocationException
195 */
196 public abstract ServiceLocationEnumeration findAttributes(
197 ServiceURL URL,
198 Vector<String> scopes,
199 Vector<String> attributeIds
200 )
201 throws ServiceLocationException;
202
203 /**
204 * For the URL and scope, return a Vector of ServiceLocationAttribute
205 * objects whose ids match the String patterns in the attributeIds Vector.
206 * The request is made in the language locale of the Locator. If no
207 * attributes match, an empty enumeration is returned. <br />
208 * <br />
209 * <em>This method is not part of the RFC 2614 interface definition.</em>
210 *
211 * @param pURL
212 * The URL for which the attributes are desired.
213 * @param pScopes
214 * A Vector of scope names. The vector should be selected from
215 * the results of a findScopes() API invocation. Use "DEFAULT"
216 * for the default scope.
217 * @param pAttributeIds
218 * A Vector of String patterns identifying the desired
219 * attributes. An empty vector means return all attributes. As
220 * described in [7], the patterns may include wildcard to match
221 * substrings. The strings may include SLP reserved characters,
222 * they will be escaped by the API before transmission.
223 * @param pDirectoryAgents
224 * A vector of InetAddress that specify the directory agents to
225 * look for.
226 * @return The enumeration
227 * @throws ServiceLocationException
228 *
229 */
230 public abstract ServiceLocationEnumeration findAttributes(
231 ServiceURL pURL,
232 Vector<String> pScopes,
233 Vector<String> pAttributeIds,
234 Vector<InetAddress> pDirectoryAgents
235 )
236 throws ServiceLocationException;
237
238 /**
239 * For the type and scope, return a Vector of all ServiceLocationAttribute
240 * objects whose ids match the String patterns in the attributeIds Vector
241 * regardless of the Locator's locale. The request is made independent of
242 * language locale. If no attributes are found, an empty vector is returned.
243 *
244 * @param pType
245 * The service type.
246 * @param pScopes
247 * A Vector of scope names. The vector should be selected from
248 * the results of a findScopes() API invocation. Use "DEFAULT"
249 * for the default scope.
250 * @param pAttributeIds
251 * A Vector of String patterns identifying the desired
252 * attributes. An empty vector means return all attributes. As
253 * described in [7], the patterns may include wildcard to match
254 * all prefixes or suffixes. The patterns may include SLP
255 * reserved characters, they will be escaped by the API before
256 * transmission.
257 * @return The enumeration
258 * @throws ServiceLocationException
259 */
260 public abstract ServiceLocationEnumeration findAttributes(
261 ServiceType pType,
262 Vector<String> pScopes,
263 Vector<String> pAttributeIds
264 )
265 throws ServiceLocationException;
266
267 /**
268 * For the type and scope, return a Vector of all ServiceLocationAttribute
269 * objects whose ids match the String patterns in the attributeIds Vector
270 * regardless of the Locator's locale. The request is made independent of
271 * language locale. If no attributes are found, an empty vector is returned. <br />
272 * <br />
273 * <em>This method is not part of the RFC 2614 interface definition.</em>
274 *
275 * @param pType
276 * The service type.
277 * @param pScopes
278 * A Vector of scope names. The vector should be selected from
279 * the results of a findScopes() API invocation. Use "DEFAULT"
280 * for the default scope.
281 * @param pAttributeIds
282 * A Vector of String patterns identifying the desired
283 * attributes. An empty vector means return all attributes. As
284 * described in [7], the patterns may include wildcard to match
285 * all prefixes or suffixes. The patterns may include SLP
286 * reserved characters, they will be escaped by the API before
287 * transmission.
288 * @param pDirectoryAgents
289 * A vector of InetAddress that specify the directory agents to
290 * look for.
291 * @return The enumeration
292 * @throws ServiceLocationException
293 */
294 public abstract ServiceLocationEnumeration findAttributes(
295 ServiceType pType,
296 Vector<String> pScopes,
297 Vector<String> pAttributeIds,
298 Vector<InetAddress> pDirectoryAgents
299 )
300 throws ServiceLocationException;
301 }