1 /*
2 (C) Copyright IBM Corp. 2007, 2012
3
4 THIS FILE IS PROVIDED UNDER THE TERMS OF THE ECLIPSE PUBLIC LICENSE
5 ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS FILE
6 CONSTITUTES RECIPIENTS ACCEPTANCE OF THE AGREEMENT.
7
8 You can obtain a current copy of the Eclipse Public License from
9 http://www.opensource.org/licenses/eclipse-1.0.php
10
11 @author : Alexander Wolf-Reber, IBM, a.wolf-reber@de.ibm.com
12 *
13 * Change History
14 * Flag Date Prog Description
15 *-------------------------------------------------------------------------------
16 * 1678915 2007-03-12 lupusalex Integrated WBEM service discovery via SLP
17 * 2003590 2008-06-30 blaschke-oss Change licensing from CPL to EPL
18 * 2524131 2009-01-21 raman_arora Upgrade client to JDK 1.5 (Phase 1)
19 * 2531371 2009-02-10 raman_arora Upgrade client to JDK 1.5 (Phase 2)
20 * 3469427 2012-01-04 blaschke-oss Fix broken HTML links
21 */
22
23 package org.metricshub.wbem.sblim.cimclient.discovery;
24
25 /*-
26 * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
27 * WBEM Java Client
28 * ჻჻჻჻჻჻
29 * Copyright 2023 - 2025 MetricsHub
30 * ჻჻჻჻჻჻
31 * Licensed under the Apache License, Version 2.0 (the "License");
32 * you may not use this file except in compliance with the License.
33 * You may obtain a copy of the License at
34 *
35 * http://www.apache.org/licenses/LICENSE-2.0
36 *
37 * Unless required by applicable law or agreed to in writing, software
38 * distributed under the License is distributed on an "AS IS" BASIS,
39 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
40 * See the License for the specific language governing permissions and
41 * limitations under the License.
42 * ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱
43 */
44
45 import java.util.Locale;
46 import java.util.Map.Entry;
47 import java.util.Set;
48 import javax.security.auth.Subject;
49 import org.metricshub.wbem.javax.wbem.client.WBEMClient;
50
51 /**
52 * Interface WBEMServiceAdvertisement is encapsulates the information collected
53 * about a service during discovery. The DMTF specifies a set a attributes that
54 * each service must advertise. These attributes are found as string constants
55 * in this interface and the method getAttribute() is offered to get an
56 * attribute by name. This design was chosen because the set of attributes might
57 * be extended by DMTF and vendor implementations. It's also unclear if upcoming
58 * new discovery protocols will have the same set of attributes as SLP.
59 *
60 * Immutable
61 * This class is thread-safe
62 * @since 2.0.2
63 */
64 public interface WBEMServiceAdvertisement {
65 /**
66 * template-type (string): The scheme name of the service scheme. The scheme
67 * name consists of the service type name and an optional naming authority
68 * name, separated from the service type name by a period. See RFC 2609
69 * section 3.2.2 for the conventions governing service type names.
70 */
71 public static final String TEMPLATE_TYPE = "template-type";
72
73 /**
74 * template-version (string): The version number of the service type
75 * specification.
76 */
77 public static final String TEMPLATE_VERSION = "template-version";
78
79 /**
80 * template-description (string): A description of the service suitable for
81 * inclusion in text read by people.
82 */
83 public static final String TEMPLATE_DESCRIPTION = "template-description";
84
85 /**
86 * template-url-syntax (string): The template-url-syntax MUST be the WBEM
87 * URI Mapping of the location of one service access point offered by the
88 * WBEM Server over TCP transport. This attribute must provide sufficient
89 * addressing information so that the WBEM Server can be addressed directly
90 * using the URL. The WBEM URI Mapping is defined in the WBEM URI Mapping
91 * Specification 1.0.0 (DSP0207).<br />
92 * <br />
93 * Example: <code>(template-url-syntax=https://localhost:5989)</cpde>
94 */
95 public static final String TEMPLATE_URL_SYNTAX = "template-url-syntax";
96
97 /**
98 * service-hi-name (string, optional): This string is used as a name of the
99 * CIM service for human interfaces. This attribute MUST be the
100 * CIM_ObjectManager.ElementName property value.
101 */
102 public static final String SERVICE_HI_NAME = "service-hi-name";
103
104 /**
105 * service-hi-description (string, optional): This string is used as a
106 * description of the CIM service for human interfaces.This attribute MUST
107 * be the CIM_ObjectManager.Description property value.
108 */
109 public static final String SERVICE_HI_DESC = "service-hi-description";
110
111 /**
112 * service-id (string, literal): The ID of this WBEM Server. The value MUST
113 * be the CIM_ObjectManager.Name property value.
114 */
115 public static final String SERVICE_ID = "service-id";
116
117 /**
118 * CommunicationMechanism (string, literal): The communication mechanism
119 * (protocol) used by the CIM Object Manager for this service-location-tcp
120 * defined in this advertisement. This information MUST be the
121 * CIM_ObjectManagerCommunicationMechanism.CommunicationMechanism property
122 * value. CIM-XML is defined in the CIM Operations over HTTP specification
123 * which can be found at http://www.dmtf.org/ <br />
124 * <br />
125 * Values: <code>"Unknown", "Other", "cim-xml"</code>
126 */
127 public static final String COMM_MECHANISM = "CommunicationMechanism";
128
129 /**
130 * OtherCommunicationMechanismDescription (string, literal, optional): The
131 * other communication mechanism defined for the CIM Server in the case the
132 * "Other" value is set in the CommunicationMechanism string. This attribute
133 * MUST be the
134 * CIM_ObjectManagerCommunicationMechanism.OtherCommunicationMechanism
135 * property value. This attribute is optional because it is only required if
136 * the "other" value is set in CommunicationMechansim. The value returned is
137 * a free-form string.
138 */
139 public static final String OTHER_COMM_MECHN_DESC = "OtherCommunicationMechanismDescription";
140
141 /**
142 * InteropSchemaNamespace (string, literal, multiple): Namespace within the
143 * target WBEM Server where the CIM Interop Schema can be accessed. Multiple
144 * namespaces may be provided. Each namespace provided MUST contain the same
145 * information.
146 */
147 public static final String INTEROP_NS = "InteropSchemaNamespace";
148
149 /**
150 * ProtocolVersion (string, literal, optional): The version of the protocol.
151 * It MUST be the CIM_ObjectManagerCommunicationMechanism.Version property
152 * value.
153 */
154 public static final String PROTOCOL_VERSION = "ProtocolVersion";
155
156 /**
157 * FunctionalProfilesSupported (string, literal, multiple):
158 * ProfilesSupported defines the CIM Operation profiles supported by the CIM
159 * Object Manager. This attribute MUST be the
160 * CIM_ObjectManagerCommunicationMechansim.FunctionalProfilesSupported
161 * property value.<br />
162 * <br />
163 * Values: <code>
164 "Unknown", "Other", "Basic Read", "Basic Write",
165 "Schema Manipulation", "Instance Manipulation",
166 "Association Traversal", "Query Execution",
167 "Qualifier Declaration", "Indications"</code>
168 */
169 public static final String FUNCTIONAL_PROF_SUPP = "FunctionalProfilesSupported";
170
171 /**
172 * FunctionalProfileDescriptions (string, literal, multiple, optional):
173 * Other profile description if the "other" value is set in the
174 * ProfilesSupported attribute. This attribute is optional because it is
175 * returned only if the "other" value is set in the ProfilesSupported
176 * attribute. If provided it MUST be equal to the
177 * CIM_ObjectManagerCommunicationMechanism.FunctionalProfileDescriptions
178 * property value.
179 */
180 public static final String FUNCTIONAL_PROF_DESC = "FunctionalProfileDescriptions";
181
182 /**
183 * MultipleOperationsSupported (boolean): Defines whether the CIM Object
184 * Manager supports batch operations. This attribute MUST be the
185 * CIM_ObjectManagerCommunicationMechanism.MultipleOperationsSupported
186 * property value.
187 */
188 public static final String MULT_OPERATIONS_SUPP = "MultipleOperationsSupported";
189
190 /**
191 * AuthenticationMechanismsSupported (string, literal, multiple): Defines
192 * the authentication mechanism supported by the CIM Object Manager. This
193 * attributed MUST be the CIM_ObjectManagerCommunicationMechanism.
194 * AuthenticationMechanismsSupported property value. <br />
195 * <br />
196 * Values: <code>"Unknown", "None", "Other", "Basic", "Digest"</code>
197 */
198 public static final String AUTH_MECH_SUPP = "AuthenticationMechanismsSupported";
199
200 /**
201 * AuthenticationMechansimDescriptions (string, literal, multiple,
202 * optional): Defines other Authentication mechanisms supported by the CIM
203 * Object Manager in the case where the "Other" value is set in any of the
204 * AuthenticationMechanismSupported attribute values. If provided, this
205 * attribute MUST be the CIM_ObjectManagerCommunicationMechanism.
206 * AuthenticationMechansimDescriptions property value.
207 */
208 public static final String AUTH_MECH_DESC = "AuthenticationMechansimDescriptions";
209
210 /**
211 * Namespace (string, literal, multiple, optional): Namespace(s) supported
212 * on the CIM Object Manager. This attribute MUST be the CIM_Namespace.name
213 * property value for each instance of CIM_Namespace that exists. This
214 * attribute is optional. NOTE: This value is literal (L) because the
215 * namespace names MUST not be translated into other languages.
216 */
217 public static final String NAMESPACE = "Namespace";
218
219 /**
220 * Classinfo (string, multiple, optional): This attributes is optional but
221 * if used, the values MUST be the CIM_Namespace.Classinfo property value.
222 * The values represent the classinfo (CIM Schema version, etc.) for the
223 * namespaces defined in the corresponding namespace listed in the Namespace
224 * attribute. Each entry in this attribute MUST correspond to the namespace
225 * defined in the same position of the namespace attribute. There must be
226 * one entry in this attribute for each entry in the namespace attribute.
227 */
228 public static final String CLASSINFO = "Classinfo";
229
230 /**
231 * RegisteredProfilesSupported (string, literal, multiple):
232 * RegisteredProfilesSupported defines the Profiles that this WBEM Server
233 * has support for. Each entry in this attribute MUST be in the form of
234 * Organization:Profile Name{:Subprofile Name}<br />
235 * <br />
236 * Examples: <br />
237 * <br />
238 * <code>
239 * DMTF:CIM Server<br />
240 * DMTF:CIM Server:Protocol Adapter<br />
241 * DMTF:CIM Server:Provider Registration <br />
242 * </code><br />
243 * The Organization MUST be the CIM_RegisteredProfile.RegisteredOrganization
244 * property value. The Profile Name MUST be the
245 * CIM_RegisteredProfile.RegisteredName property value. The subprofile Name
246 * MUST be the CIM_RegisteredProfile.RegisteredName property value when it
247 * is used as a Dependent in the CIM_SubProfileRequiresProfile association
248 * for the specified Profile Name (used as the antecedent).
249 *
250 */
251 public static final String REG_PROF_SUPP = "RegisteredProfilesSupported";
252
253 /**
254 * Gets the URL of the directory from which this advertisement was received
255 *
256 * @return The directory URL
257 */
258 public abstract String getDirectory();
259
260 /**
261 * Returns the concrete service type. E.g. for the SLP advertised service
262 * <code>service:wbem:https</code> this method would return
263 * <code>https</code>.
264 *
265 * @return The concrete service type
266 */
267 public abstract String getConcreteServiceType();
268
269 /**
270 * Returns the interop namespaces
271 *
272 * @return The interop namespaces
273 */
274 public abstract String[] getInteropNamespaces();
275
276 /**
277 * Returns the service url, e.g. http://9.155.62.79:5988
278 *
279 * @return The service url
280 */
281 public abstract String getServiceUrl();
282
283 /**
284 * Return the attribute value for a given attribute name
285 *
286 * @param pAttributeName
287 * The attribute name
288 * @return The value
289 */
290 public abstract String getAttribute(String pAttributeName);
291
292 /**
293 * Return the set of attributes of this advertisement
294 *
295 * @return A Set<Map.Entry<String, String>> containing the name
296 * value pairs of the attributes.
297 */
298 public abstract Set<Entry<String, String>> getAttributes();
299
300 /**
301 * Returns the service id
302 *
303 * @return The service id
304 */
305 public abstract String getServiceId();
306
307 /**
308 * Returns the expiration state of the advertisement.
309 *
310 * @return <code>true</code> when advertisement is expired.
311 */
312 public abstract boolean isExpired();
313
314 /**
315 * Sets the expirations state of the advertisement. Might be used by the
316 * application to mark an advertisement as expired, e.g. when it's no longer
317 * reported by the corresponding directory. Used for this purpose by
318 * AdvertisementCatalog.
319 *
320 * @param pExpired
321 * The new value
322 */
323 public abstract void setExpired(boolean pExpired);
324
325 /**
326 * Creates a fully-initialized WBEMClient instance connected to the service
327 * that is subject of this advertisement. On every call to this method a new
328 * client will be created. The client is not stored or cached anywhere in
329 * this class.
330 *
331 * @param pSubject
332 * The credential for authenticating with the service
333 * @param pLocales
334 * An array of locales ordered by preference
335 * @return The WBEM client
336 * @throws Exception
337 * @pattern Factory Methods
338 */
339 public abstract WBEMClient createClient(Subject pSubject, Locale[] pLocales) throws Exception;
340 }