1 /*------------------------------------------------------------------------------
  2 Name:      ConnectQos.java
  3 Project:   xmlBlaster.org
  4 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
  5 ------------------------------------------------------------------------------*/
  6 package org.xmlBlaster.client.qos;
  7 
  8 import org.xmlBlaster.authentication.plugins.I_ClientPlugin;
  9 import org.xmlBlaster.authentication.plugins.I_SecurityQos;
 10 import org.xmlBlaster.util.Global;
 11 import org.xmlBlaster.util.SessionName;
 12 import org.xmlBlaster.util.XmlBlasterException;
 13 import org.xmlBlaster.util.def.Constants;
 14 import org.xmlBlaster.util.qos.ClientProperty;
 15 import org.xmlBlaster.util.qos.ConnectQosData;
 16 import org.xmlBlaster.util.qos.SessionQos;
 17 import org.xmlBlaster.util.qos.address.Address;
 18 import org.xmlBlaster.util.qos.address.AddressBase;
 19 import org.xmlBlaster.util.qos.address.CallbackAddress;
 20 import org.xmlBlaster.util.qos.storage.CbQueueProperty;
 21 import org.xmlBlaster.util.qos.storage.ClientQueueProperty;
 22 
 23 
 24 /**
 25  * This class encapsulates the qos of a connect() invocation.
 26  * <p />
 27  * @see org.xmlBlaster.util.qos.ConnectQosSaxFactory
 28  * @see <a href="http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.connect.html">connect interface</a>
 29  */
 30 public final class ConnectQos
 31 {
 32    private final Global glob;
 33    private final ConnectQosData connectQosData;
 34    private boolean doSendConnect=true;
 35    /** Access to encrypt/decrypt framework, used by protocol plugins */
 36    //private I_MsgSecurityInterceptor securityInterceptor;
 37 
 38    /**
 39     * Default constructor.
 40     * <p>
 41     * Initializes login credentials from environment e.g. <i>-session.name guest</i> and <i>-passwd secret</i> with
 42     * the default security plugin as given by <i>-Security.Client.DefaultPlugin htpasswd,1.0</i>
 43     * </p>
 44     * <p>
 45     * To use another security authentication plugin use setSecurity()
 46     * @exception XmlBlasterException on problems loading the client security plugin
 47     */
 48    public ConnectQos(Global glob) throws XmlBlasterException {
 49       this.glob = (glob==null) ? Global.instance() : glob;
 50       this.connectQosData = new ConnectQosData(this.glob);
 51       init();
 52    }
 53 
 54    /**
 55     * Login with the default security plugin as given by <i>-Security.Client.DefaultPlugin htpasswd,1.0</i>
 56     * @param userId e.g. "joe" or "joe/7" if you want to connect to joe's seventh session
 57     * @param passwd The password if you use a password based authentication
 58     * @exception XmlBlasterException if the default security plugin couldn't be loaded
 59     */
 60    public ConnectQos(Global glob, String userId, String passwd) throws XmlBlasterException {
 61       this.glob = (glob==null) ? Global.instance() : glob;
 62       this.connectQosData = new ConnectQosData(this.glob, this.glob.getConnectQosFactory(), null, null);
 63       this.connectQosData.loadClientPlugin(null, null, userId, passwd);
 64       init();
 65    }
 66 
 67    /**
 68     * Constructor for special use in cluster environment only.
 69     */
 70    public ConnectQos(Global glob, ConnectQosData connectQosData) {
 71       this.glob = (glob==null) ? Global.instance() : glob;
 72       this.connectQosData = connectQosData;
 73       init();
 74    }
 75 
 76    private void init() {
 77       this.doSendConnect = this.glob.getProperty().get("dispatch/connection/doSendConnect", true);
 78    }
 79 
 80    public ConnectQosData getData() {
 81       return this.connectQosData;
 82    }
 83 
 84    /**
 85     * @return The session QoS which contains all session specific configuration, never null
 86     */
 87    public SessionQos getSessionQos() {
 88       return this.connectQosData.getSessionQos();
 89    }
 90 
 91    /**
 92     * Set the login session name.
 93     * <p>
 94     * This will NOT set the security loginName (see setUserId()).
 95     * </p>
 96     * @param sessionName e.g. "joe" which is the loginName (subjectId) only<br />
 97     *        e.g. "joe/2" which forces a connect on the public session ID 2 of user joe
 98     */
 99    public void setSessionName(SessionName sessionName) {
100       getSessionQos().setSessionName(sessionName);
101    }
102 
103    public SessionName getSessionName() {
104       return getSessionQos().getSessionName();
105    }
106 
107    /**
108     * Timeout until session expires if no communication happens
109     * @param timeout The login session will be destroyed after given milliseconds.<br />
110     *                Session lasts forever if set to 0L
111     */
112    public void setSessionTimeout(long timeout) {
113       getSessionQos().setSessionTimeout(timeout);
114    }
115 
116    /**
117     * Set the secret sessionId.
118     * Usually never used, the secret sessionId is generated by the server
119     */
120    public void setSecretSessionId(String id) {
121       this.connectQosData.getSessionQos().setSecretSessionId(id);
122    }
123 
124    /**
125     * Set the secret cbSessionId.
126     * This is bounced back in the <code>update(cbSessionId, ...)</code>
127     */
128    public void setSecretCbSessionId(String id) {
129       this.connectQosData.getCurrentCallbackAddress().setSecretCbSessionId(id);
130    }
131 
132    /**
133     * If maxSession == 1, only a single login is possible
134     * @param max How often the same client may login
135     */
136    public void setMaxSessions(int max) {
137       this.connectQosData.getSessionQos().setMaxSessions(max);
138    }
139 
140    /**
141     * If clearSessions is true, all old sessions of this user are discarded.
142     * @param clear Defaults to false
143     */
144    public void clearSessions(boolean clear) {
145       this.connectQosData.getSessionQos().clearSessions(clear);
146    }
147 
148    /**
149     * If clearSessions is true, all old sessions of this user are discarded.
150     */
151    public final boolean clearSessions() {
152       return this.connectQosData.getSessionQos().clearSessions();
153    }
154 
155    /**
156     * @return refreshSession is true if the client automatically notifies xmlBlaster that it is alive
157     * and the login session is extended
158     */
159    public final boolean getRefreshSession() {
160       return this.connectQosData.getRefreshSession();
161    }
162 
163    /**
164     * @param refreshSession true: The client automatically notifies xmlBlaster that it is alive
165     * and the login session is extended
166     */
167    public final void setRefreshSession(boolean refreshSession) {
168       this.connectQosData.setRefreshSession(refreshSession);
169    }
170 
171    /**
172     * Allows to set or overwrite the login name for I_SecurityQos.
173     * <p>
174     * This will call setSessionName() as well if sessionName is not set yet.
175     * </p>
176     * This is a convenience method to set the securityQos userId
177     *
178     * @param loginName The unique user id
179     */
180    public void setUserId(String loginName) throws XmlBlasterException {
181       this.connectQosData.setUserId(loginName);
182    }
183 
184    /**
185     * @return The user ID or "NoLoginName" if not known
186     */
187    public String getUserId() {
188       return this.connectQosData.getUserId();
189    }
190 
191    /**
192     * Allows to set or overwrite the client side security plugin.
193     *
194     * @param type The client side security plugin to use
195     * @param credential For 'htpasswd' the password, if null the environment -passwd is checked (default plugin)
196     * @see ConnectQosData#loadClientPlugin(String, String, String, String)
197     */
198    public I_ClientPlugin loadClientPlugin(String type, String version, String userId, String credential) throws XmlBlasterException {
199    //public void setSecurityPluginData(String mechanism, String version, String loginName, String passwd) throws XmlBlasterException {
200       return this.connectQosData.loadClientPlugin(type, version, userId, credential);
201    }
202 
203    /**
204     * Access the default plugin or the previously added by load loadClientPlugin()
205     */
206    public I_ClientPlugin getClientPlugin() {
207       return this.getClientPlugin();
208    }
209 
210    /*
211     * Allows to specify how you want to identify yourself.
212     * <p />
213     * Usage to login to xmlBlaster with a password approach:
214     * <pre>
215     *    import org.xmlBlaster.authentication.plugins.simple.SecurityQos;
216     *    ...
217     *    ConnectQosData qos = new ConnectQosData(null);
218     *    qos.setSecurityQos(new SecurityQos("joe", "secret"));
219     *    xmlBlasterConnection.connect(qos);
220     * </pre>
221     * NOTE: Usually loadClientPlugin() is easier to use.
222     * @deprecated This is specific to the loaded I_ClientPlugin, please use getClientPlugin().setSecurityQos()
223     */
224    //public void setSecurityQos(I_SecurityQos securityQos) {
225    //   this.connectQosData.setSecurityQos(securityQos);
226    //}
227 
228    /**
229     * This is a convenience method for <code>getClientPlugin().getSecurityQos()</code>.
230     * @return Access the login credentials or null if not set
231     */
232    public I_SecurityQos getSecurityQos() {
233       return this.connectQosData.getSecurityQos();
234    }
235 
236    /**
237     * Return the type of the referenced SecurityPlugin.
238     * <p/>
239     * This is a convenience access similiar to
240     * <code>getClientPlugin().getPluginType()</code>
241     *
242     * @return The type or null if not known
243     */
244    //public String getSecurityPluginType() {
245    //   return this.connectQosData.getSecurityPluginType();
246    //}
247 
248    /**
249     * Return the version of the referenced SecurityPlugin.
250     * <p/>
251     * This is a convenience access similiar to
252     * <code>getClientPlugin().getPluginVersion()</code>
253     *
254     * @return The version or null if not known
255     */
256    //public String getSecurityPluginVersion() {
257    //   return this.connectQosData.getSecurityPluginVersion();
258    //}
259 
260    /**
261     * @param Set if we accept point to point messages
262     */
263    public void setPtpAllowed(boolean ptpAllowed) {
264       this.connectQosData.setPtpAllowed(ptpAllowed);
265    }
266 
267    /**
268     * @return true if we are accepting PtP messages
269     */
270    public boolean isPtpAllowed() {
271       return this.connectQosData.isPtpAllowed();
272    }
273 
274    /**
275     * @param Set if we allow multiple updates for the same message if we have subscribed multiple times to it.
276     * @deprecated Please use multiSubscribe=false from SubscribeQos
277     */
278    public void setDuplicateUpdates(boolean duplicateUpdates) {
279       this.connectQosData.setDuplicateUpdates(duplicateUpdates);
280    }
281 
282    /**
283     * @return true if we allow multiple updates for the same message if we have subscribed multiple times to it.
284     * @deprecated Please use multiSubscribe=false from SubscribeQos
285     */
286    public boolean duplicateUpdates() {
287       return this.connectQosData.duplicateUpdates();
288    }
289 
290    /**
291     * The configuration of the local client side queue.
292     * @return never null
293     */
294    public ClientQueueProperty getClientQueueProperty() {
295       return this.connectQosData.getClientQueueProperty();
296    }
297 
298    /**
299     * The configuration of the local client side queue.
300     * @param Your hardcoded configuration
301     */
302    public void addClientQueueProperty(ClientQueueProperty clientQueueProperty) {
303       this.connectQosData.addClientQueueProperty(clientQueueProperty);
304    }
305 
306    /**
307     * Set the address to which we want to connect, with all the configured parameters.
308     * <p />
309     * @param address  An object containing the protocol (e.g. EMAIL) the address (e.g. hugo@welfare.org) and the connection properties
310     */
311    public void setAddress(Address address) {
312       this.connectQosData.setAddress(address);
313    }
314 
315    /**
316     * The connection address and properties of the xmlBlaster server
317     * we want connect to.
318     * @return never null
319     */
320    public Address getAddress() {
321       return this.connectQosData.getAddress();
322    }
323 
324    /**
325     * The connection address and properties of the xmlBlaster server
326     * we want connect to.
327     * @return never null
328     */
329    public AddressBase[] getAddresses(boolean forceCbAddressCreation) {
330       return this.connectQosData.getAddresses(forceCbAddressCreation);
331    }
332 
333    /**
334     * Add a callback address where to send the message (for PtP or subscribes).
335     * <p />
336     * Creates a default CbQueueProperty object to hold the callback address argument.<br />
337     * Note you can invoke this multiple times to allow multiple callbacks.
338     * @param callback  An object containing the protocol (e.g. EMAIL) and the address (e.g. hugo@welfare.org)
339     */
340    public void addCallbackAddress(CallbackAddress callback) {
341       this.connectQosData.addCallbackAddress(callback);
342    }
343 
344    /**
345     * Adds a queue description.
346     * This allows to set all supported attributes of a callback queue and a callback address
347     * @param prop The property object of the callback queue which shall be established in the server for calling us back.
348     * @see org.xmlBlaster.util.qos.address.CallbackAddress
349     */
350    public void setSessionCbQueueProperty(CbQueueProperty prop) {
351       this.connectQosData.setSessionCbQueueProperty(prop);
352    }
353 
354    /**
355     * Returns never null.
356     * <p />
357     * If no CbQueueProperty exists, a RELATING_CALLBACK queue property object is created
358     * on the fly.
359     */
360    public CbQueueProperty getSessionCbQueueProperty() {
361       return this.connectQosData.getSessionCbQueueProperty();
362    }
363 
364    /**
365     * The number of bytes of stringified qos
366     */
367    public int size() {
368       return this.connectQosData.size();
369    }
370 
371    /**
372     * Converts the data into a valid XML ASCII string.
373     * @return An XML ASCII string
374     */
375    public String toString() {
376       return toXml();
377    }
378 
379    /**
380     * Converts the data into a valid XML ASCII string.
381     * @return An XML ASCII string
382     */
383    public String toXml() {
384       return this.connectQosData.toXml();
385    }
386 
387    /**
388     * Access the security interceptor to encrypt/decrypt.
389     * @return I_MsgSecurityInterceptor plugin or null
390     * @deprecated No use for this
391     */
392    //public I_MsgSecurityInterceptor getSecurityInterceptor() {
393    //   return this.securityInterceptor;
394    //}
395 
396    /*
397     * Access the security interceptor to encrypt/decrypt.
398     * @return I_MsgSecurityInterceptor
399     * @deprecated No use for this
400    //public void setSecurityInterceptor(I_MsgSecurityInterceptor securityInterceptor) {
401    //   this.securityInterceptor = securityInterceptor;
402    //}
403    */
404    
405    /**
406     * Sets a client property (an application specific property) to the
407     * given value
408     * @param key
409     * @param value
410     */
411    public void addClientProperty(String key, Object value) {
412       this.connectQosData.addClientProperty(key, value);
413    }
414 
415    /**
416     * Read back a property.
417     * @return The client property or null if not found
418     */
419    public ClientProperty getClientProperty(String key) {
420       return this.connectQosData.getClientProperty(key);
421    }
422 
423    /**
424     * sets the persistent flag for this subscription. If this flag is
425     * set, the subscription will persit a server crash.
426     * @param persistent
427     */
428    public void setPersistent(boolean persistent) {
429       this.connectQosData.setPersistent(persistent);
430    }
431 
432    /**
433     * Gets the persistent flag. If this flag is
434     * set, the session will persist a server crash.
435     * @return true if persistent false otherwise.
436     */
437    public boolean getPersistent() {
438       return this.connectQosData.getPersistentProp().getValue();
439    }
440 
441    /**
442     * Get a usage string for the connection parameters
443     */
444    public String usage() {
445       String text = "\n";
446       text += getSessionQos().usage();
447       return text;
448    }
449 
450    /**
451     * Sets the queue properties for the subject queue of this subject
452     * @param subjectQueueProperty
453     */
454    public void setSubjectQueueProperty(CbQueueProperty subjectQueueProperty) {
455       this.connectQosData.setSubjectQueueProperty(subjectQueueProperty);
456    }
457 
458    /**
459     * Gets the subject queue properties as set on this connection.
460     * @return the properties
461     */
462    public CbQueueProperty getSubjectQueueProperty() {
463       return this.connectQosData.getSubjectQueueProperty();
464    }
465 
466    /**
467     * @return Returns the doSendConnect.
468     */
469    public boolean doSendConnect() {
470       return this.doSendConnect;
471    }
472 
473    /**
474     * If set to false the connect() is not send to the
475     * server. In this case the client library is completely
476     * initialized and you can receive for example callback
477     * messages over 'email' or 'XMLRPC' protocols.<br />
478     * This is useful for clients which can't connect
479     * themselves (for example because of a firewall) and
480     * have a delegate client which does the real connect
481     * and possible subscribes.
482     * <br />
483     * Can be changed on command line with '-dispatch/connection/doSendConnect false'
484     * or in a property file.
485     * @param doSendConnect Overwrites default or value from environment
486     */
487    public void doSendConnect(boolean doSendConnect) {
488       this.doSendConnect = doSendConnect;
489    }
490 
491    /**
492     *  For testing invoke: java org.xmlBlaster.client.qos.ConnectQos
493     */
494    public static void main( String[] args ) throws XmlBlasterException {
495       {
496          ConnectQos qos =new ConnectQos(new Global(args), "joe/2", "secret");//new SessionName(glob, "joe"));
497          qos.addClientProperty(Constants.UPDATE_BULK_ACK, "true");
498          System.out.println(qos.toXml());
499       }
500       {
501          ConnectQos qos =new ConnectQos(null);
502          System.out.println("Minimal:" + qos.toXml());
503       }
504    }
505 }


syntax highlighted by Code2HTML, v. 0.9.1