1 /*
2 WBEMClientSBLIM.java
3
4 (C) Copyright IBM Corp. 2006, 2013
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 : Alexander Wolf-Reber, IBM, a.wolf-reber@de.ibm.com
14 *
15 * Change History
16 * Flag Date Prog Description
17 *-------------------------------------------------------------------------------
18 * 1565892 2006-11-08 lupusalex Make SBLIM client JSR48 compliant
19 * 2003590 2008-06-30 blaschke-oss Change licensing from CPL to EPL
20 * 2524131 2009-01-21 raman_arora Upgrade client to JDK 1.5 (Phase 1)
21 * 2763216 2009-04-14 blaschke-oss Code cleanup: visible spelling/grammar errors
22 * 2942520 2010-03-08 blaschke-oss IPv6 link local address with scope_id including a dot not supported
23 * 3516848 2012-04-11 blaschke-oss enumerateNamespaces() method to WBEMClient
24 * 3522904 2012-05-02 blaschke-oss Add new API WBEMClientSBLIM.isActive()
25 * 2616 2013-02-23 blaschke-oss Add new API WBEMClientSBLIM.sendIndication()
26 */
27
28 package org.metricshub.wbem.sblim.cimclient;
29
30 /*-
31 * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
32 * WBEM Java Client
33 * ჻჻჻჻჻჻
34 * Copyright 2023 - 2025 MetricsHub
35 * ჻჻჻჻჻჻
36 * Licensed under the Apache License, Version 2.0 (the "License");
37 * you may not use this file except in compliance with the License.
38 * You may obtain a copy of the License at
39 *
40 * http://www.apache.org/licenses/LICENSE-2.0
41 *
42 * Unless required by applicable law or agreed to in writing, software
43 * distributed under the License is distributed on an "AS IS" BASIS,
44 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
45 * See the License for the specific language governing permissions and
46 * limitations under the License.
47 * ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱
48 */
49
50 import java.net.URI;
51 import java.util.Locale;
52 import java.util.Properties;
53 import javax.net.SocketFactory;
54 import javax.security.auth.Subject;
55 import org.metricshub.wbem.javax.cim.CIMInstance;
56 import org.metricshub.wbem.javax.cim.CIMObjectPath;
57 import org.metricshub.wbem.javax.wbem.CloseableIterator;
58 import org.metricshub.wbem.javax.wbem.WBEMException;
59 import org.metricshub.wbem.javax.wbem.client.WBEMClient;
60
61 /**
62 * Class WBEMClientSBLIM contains the SBLIM CIM Client specific extensions to
63 * the WBEMClient interface.
64 *
65 * @see WBEMClient
66 *
67 */
68 public interface WBEMClientSBLIM extends WBEMClient {
69 /**
70 * Initialize the client connection. This must be called before any
71 * operations. This must only be called once.
72 *
73 * @param pUri
74 * The protocol and host to use. Any other fields will be
75 * ignored.
76 * @param pSubject
77 * The principal/credential pairs for this connection.
78 * @param pLocales
79 * An array of locales in order of priority of preference.
80 * @throws IllegalArgumentException
81 * If the host or scheme portion of the object path is null, or
82 * if the protocol is not supported.
83 * @throws WBEMException
84 * If the protocol adapter or security cannot be initialized.
85 */
86 public void initialize(URI pUri, Subject pSubject, Locale[] pLocales) throws IllegalArgumentException, WBEMException;
87
88 /**
89 * Returns the client specific configuration properties. Note that only
90 * these properties are returned that override the global settings. The
91 * global settings can be accessed via the <code>java.lang.System</code>
92 * class.<br />
93 * If the no client specific configuration is set, this method returns
94 * <code>null</code>
95 *
96 * @return The configuration properties
97 * @see System#getProperties()
98 */
99 public Properties getProperties();
100
101 /**
102 * Sets the client specific configuration properties. Any previously set
103 * client specific properties are overwritten. The given properties are
104 * handled as an overlay on the global settings. That means that properties
105 * specified here override the corresponding global properties whereas
106 * properties not specified here are taken from the global properties. The
107 * global settings can be accessed via the <code>java.lang.System</code>
108 * class.
109 *
110 * @param pProperties
111 * The session specific properties. <code>null</code> resets this
112 * client to the global settings.
113 *
114 * @see System#setProperties(Properties)
115 */
116 public void setProperties(Properties pProperties);
117
118 /**
119 * Returns the effective value of a given configuration property. The method
120 * will return the local value of the current thread if one was set or
121 * otherwise client specific value if one was set or otherwise the global
122 * value if one was set or otherwise the default value. Valid property names
123 * can be found in the <code>WBEMConfigurationProperties</code> interface.
124 *
125 * @param pKey
126 * The name of the configuration property
127 *
128 * @return The value of the given configuration property
129 * @see WBEMConfigurationProperties
130 */
131 public String getProperty(String pKey);
132
133 /**
134 * Sets a client specific configuration property. This property will
135 * override the corresponding global property for this client instance. The
136 * global settings can be accessed via the <code>java.lang.System</code>
137 * class. Valid property names can be found in the
138 * <code>WBEMConfigurationProperties</code> interface. Unknown properties
139 * are ignored.
140 *
141 * @param pKey
142 * The name of the configuration property
143 * @param pValue
144 * The value of the configuration property. <code>null</code>
145 * resets to the global setting.
146 * @see WBEMConfigurationProperties
147 * @see System#setProperty(String, String)
148 */
149 public void setProperty(String pKey, String pValue);
150
151 /**
152 * Returns the configuration properties that are local to the current
153 * thread. Note that only these properties are returned that override the
154 * global and the client settings. The global settings can be accessed via
155 * the <code>java.lang.System</code> class, the client setting via
156 * <code>getProperties()</code>.<br />
157 * If the no client specific configuration is set, this method returns
158 * <code>null</code>
159 *
160 * @return The configuration properties
161 * @see System#getProperties()
162 * @see #getProperties()
163 */
164 public Properties getLocalProperties();
165
166 /**
167 * Sets the configuration properties that are local to the current thread.
168 * Any previously set local properties (of the current thread) are
169 * overwritten. The given properties are handled as an overlay on the global
170 * settings and the client settings. That means that properties specified
171 * here override the corresponding properties whereas properties not
172 * specified here are taken from the client or global properties. The global
173 * settings can be accessed via the <code>java.lang.System</code> class, the
174 * client setting via <code>getProperties()</code>.
175 *
176 * @param pProperties
177 * The thread specific properties. <code>null</code> remove the
178 * local setting of the current thread.
179 *
180 * @see System#setProperties(Properties)
181 * @see #setProperties(Properties)
182 */
183 public void setLocalProperties(Properties pProperties);
184
185 /**
186 * Sets a local configuration property for the current thread. This property
187 * will override the corresponding global and client property for this
188 * client instance. The global settings can be accessed via the
189 * <code>java.lang.System</code> class, the client setting via
190 * <code>getProperties()</code>. Valid property names can be found in the
191 * <code>WBEMConfigurationProperties</code> interface. Unknown properties
192 * are ignored.
193 *
194 * @param pKey
195 * The name of the configuration property
196 * @param pValue
197 * The value of the configuration property. <code>null</code>
198 * resets to the global setting.
199 * @see WBEMConfigurationProperties
200 * @see System#setProperty(String, String)
201 * @see #setProperty(String, String)
202 */
203 public void setLocalProperty(String pKey, String pValue);
204
205 /**
206 * Gets the custom socket factory if one is set. The client uses this
207 * factory for socket creation instead of the default one.
208 *
209 * @return The custom factory used for socket creation. <code>null</code>
210 * indicates set the JRE default factory is used.
211 */
212 public SocketFactory getCustomSocketFactory();
213
214 /**
215 * Sets a custom socket factory. The client will use this factory for socket
216 * creation instead of the JRE default.
217 *
218 * @param pFactory
219 * The factory to use for socket creation. <code>null</code>
220 * resets to the JRE default factory.
221 * @throws UnsupportedOperationException
222 * Some protocols might not communicate via TCP sockets
223 */
224 public void setCustomSocketFactory(SocketFactory pFactory) throws UnsupportedOperationException;
225
226 /**
227 * Enumerate the names of the instances of CIM namespaces.
228 *
229 * @param pNamespace
230 * The Interop Namespace, if known. If null, the default Interop
231 * Namespace names defined by DSP1033 are used.
232 * @return A <code>CloseableIterator</code> of <code>CIMObjectPath</code>s.
233 * @throws WBEMException
234 * If unsuccessful, one of the following status codes must be
235 * returned. The ORDERED list is:
236 *
237 * <pre>
238 * CIM_ERR_FAILED (some other unspecified error occurred)
239 * </pre>
240 */
241 public CloseableIterator<CIMObjectPath> enumerateNamespaces(String pNamespace) throws WBEMException;
242
243 /**
244 * Returns an indication of whether the client is active (initialized and
245 * not closed) or inactive (not initialized or closed).
246 *
247 * @return <code>true</code> if client is active, <code>false</code>
248 * otherwise.
249 */
250 public boolean isActive();
251
252 /**
253 * Sends the indication to the specified recipient.
254 *
255 * @param pRecipient
256 * URI of indication recipient.
257 * @param pIndication
258 * Indication.
259 * @return <code>true</code> if indication received successfully,
260 * <code>false</code> otherwise.
261 * @throws WBEMException
262 * If unsuccessful, one of the following status codes must be
263 * returned. The ORDERED list is:
264 *
265 * <pre>
266 * CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized
267 * or otherwise incorrect parameters)
268 * CIM_ERR_FAILED (some other unspecified error occurred)
269 * </pre>
270 */
271 public boolean sendIndication(URI pRecipient, CIMInstance pIndication) throws WBEMException;
272 }