BasicOps


1   package com.ca.commons.jndi;
2   
3   import java.util.Properties  ;
4   import java.util.Hashtable  ;
5   import javax.naming.*;
6   import javax.naming.directory.*;
7   import java.util.logging.*;
8   
9   
10  /**
11   * <p>The BasicOps class contains methods for performing basic
12   * directory operations.  Errors are generally caught and handled locally,
13   * although return codes usually indicate the general success status of
14   * operations.  </p>
15   * <p/>
16   * <p>Two methods, error() and log() are defined.  These are intended to be
17   * over-ridden by programs wishing application specific handling of these
18   * (i.e. for more sensible user output than System.out.println()...).</p
19   */
20  
21  public class BasicOps extends JNDIOps
22  {
23      private final static Logger log = Logger.getLogger(BasicOps.class.getName());
24  
25      protected int ldapVersion = -1;  // ldap version of the current connection (-1 = not connected)
26  
27      String   errorMsg;                     //TE: a record of the last error msg.
28      Exception   errorException = null;     //TE: a record of the last exception.
29  
30  
31      /**
32       * Initialise a Basic Operation object with a context.
33       */
34  
35      public BasicOps(DirContext c)
36              throws NamingException
37      {
38          super(c);
39          setLdapVersion(c.getEnvironment());
40      }
41  
42      /**
43       * Create a new BasicOps object, initialised
44       * with an ldap context created from the connectionData,
45       * and maintaining a reference to that connectionData.
46       *
47       * @param cData contains all the connection details.  (Effectively
48       *              a structured form of the jndi environment object).
49       */
50      public BasicOps(ConnectionData cData)
51              throws NamingException
52      {
53          super(cData.getJNDIEnvironment());
54      }
55  
56      /**
57       * Factory Method to create BasicOps objects, initialised
58       * with an ldap context created from the connectionData,
59       * and maintaining a reference to that connectionData.
60       *
61       * @param cData the details of the directory to connect to
62       * @return a BasicOps object.
63       */
64  
65      public static BasicOps getInstance(ConnectionData cData)
66              throws NamingException
67      {
68          BasicOps newObject = new BasicOps(cData);
69          return newObject;
70      }
71  
72      /**
73       * Open an initial context.
74       * Will open an initial context which can then be used to construct a
75       * BasicOps object. Note that this method may take some time to return.
76       *
77       * @param connectionData a data object contain all the connection details.
78       */
79  
80      public static DirContext openContext(ConnectionData connectionData)
81              throws NamingException
82      {
83          return openContext(connectionData.getJNDIEnvironment());
84      }
85  
86  
87      /**
88       * This static ftn. can be used to open an initial context (which can then
89       * be used to construct a BasicOps object).  Note that this ftn may take some
90       * time to return...
91       *
92       * @param version       the LDAP Version (2 or 3) being used.
93       * @param host          the LDAP server name.
94       * @param port          the LDAP server port (default 389) being used.
95       * @param user          the Manager User's DN - (is null if user is not manager)
96       * @param pwd           the Manager User's password - (is null if user is not manager)
97       * @param tracing       whether to set BER tracing on or not
98       * @param referralType  the jndi ldap referral type: [follow:ignore:throw]
99       * @param aliasHandling how aliases should be handled in searches ('always'|'never'|'find'|'search')
100      * @return The created context.
101      * @deprecated use getInstance() instead
102      */
103 
104     public static DirContext openContext(int version, String   host, int port, String   user, char[] pwd,
105                                          boolean tracing, String   referralType, String   aliasHandling)
106             throws NamingException
107     {
108         if (host == null)
109             throw new NamingException("Host not specified in openContext()!");
110 
111         if (port == 0) port = 389;
112 
113         return openContext(version, ("ldap://" + host + ":" + port), user, pwd, tracing, referralType, aliasHandling);
114     }
115 
116 
117     /**
118      * Opens a simple default initial context, with no authentication, using version 3 ldap.
119      *
120      * @deprecated use getInstance() instead.
121      */
122 
123     public static DirContext openContext(String   url)
124             throws NamingException
125     {
126         ConnectionData myData = new ConnectionData();
127         myData.url = url;
128 
129         return openContext(3,
130                 url,
131                 "",
132                 null,
133                 false,
134                 null,
135                 null,
136                 false,
137                 null,
138                 null,
139                 null,
140                 null,
141                 null,
142                 null,
143                 false);
144     }
145 
146 
147     /**
148      * Opens an initial context with (optional) authentication and configurable ldap version.
149      *
150      * @param version       the LDAP Version (2 or 3) being used.
151      * @param url           a url of the form ldap://hostname:portnumber
152      * @param managerUserDN the Manager User's distinguished name (optionally null if not used)
153      * @param pwd           the Manager User's password - (is null if user is not manager)
154      */
155 /*
156    public static DirContext openContext(int version, String url, String userDN,
157                                         char[] pwd, boolean tracing,
158                                         String referralType, String aliasType,
159                                         boolean useSSL, String cacerts, String clientcerts,
160                                         char[] caKeystorePwd, char[] clientKeystorePwd,
161                                         String caKeystoreType, String clientKeystoreType )
162 */
163 
164     public static DirContext openContext(int version,
165                                          String   url,
166                                          String   managerUserDN,
167                                          char[] pwd)
168             throws NamingException
169     {
170         return openContext(version,
171                 url,
172                 managerUserDN,
173                 pwd,
174                 false,
175                 null,
176                 null,
177                 false,
178                 null,
179                 null,
180                 null,
181                 null,
182                 null,
183                 null,
184                 false);
185     }
186 
187 
188     /**
189      * This static ftn. can be used to open an initial context (which can then
190      * be used to construct a BasicOps object).  Note that this ftn may take some
191      * time to return...
192      *
193      * @param version       the LDAP Version (2 or 3) being used.
194      * @param url           a url of the form ldap://hostname:portnumber
195      * @param userDN        the Manager User's distinguished name (optionally null if not used)
196      * @param pwd           the Manager User's password - (is null if user is not manager)
197      * @param tracing       whether to set BER tracing on or not
198      * @param referralType  the jndi ldap referral type: [follow:ignore:throw] (may be null - defaults to 'follow')
199      * @param aliasHandling
200      * @return The created context.
201      * @deprecated use getInstance() instead
202      */
203 
204     public static DirContext openContext(int version, String   url, String   userDN, char[] pwd, boolean tracing, String   referralType, String   aliasHandling)
205             throws NamingException
206     {
207         return openContext(version,
208                 url,
209                 userDN,
210                 pwd,
211                 tracing,
212                 referralType,
213                 aliasHandling,
214                 false,
215                 null,
216                 null,
217                 null,
218                 null,
219                 null,
220                 null,
221                 false);
222     }
223      /**
224      * This static ftn. can be used to open an initial context (which can then
225      * be used to construct a BasicOps object).  Note that this ftn may take some
226      * time to return...
227      *
228      * @param version            the LDAP Version (2 or 3) being used.
229      * @param url                a url of the form ldap://hostname:portnumber.
230      * @param userDN             the Manager User's distinguished name (optionally null if not used).
231      * @param pwd                the Manager User's password - (is null if user is not manager).
232      * @param tracing            whether to set BER tracing on or not.
233      * @param referralType       the jndi ldap referral type: [follow:ignore:throw] (may be null - defaults to 'follow').
234      * @param aliasType          how aliases should be handled in searches ('always'|'never'|'find'|'search').
235      * @param useSSL             whether to use SSL (either simple or client-authenticated).
236      * @param cacerts            the file containing the trusted server certificates (no keys).
237      * @param clientcerts        the file containing client certificates.
238      * @param caKeystorePwd      the password to the ca's keystore (may be null for non-client authenticated ssl).
239      * @param clientKeystorePwd  the password to the client's keystore (may be null for non-client authenticated ssl).
240      * @param caKeystoreType     the type of keystore file; e.g. 'JKS', or 'PKCS12'.
241      * @param clientKeystoreType the type of keystore file; e.g. 'JKS', or 'PKCS12'.
242      * @return The created context.
243       * @deprecated use longer version with 'useGSSAPI' option instead.
244      */
245 
246     public static DirContext openContext(int version,
247                                          String   url,
248                                          String   userDN,
249                                          char[] pwd,
250                                          boolean tracing,
251                                          String   referralType,
252                                          String   aliasType,
253                                          boolean useSSL,
254                                          String   cacerts,
255                                          String   clientcerts,
256                                          char[] caKeystorePwd,
257                                          char[] clientKeystorePwd,
258                                          String   caKeystoreType,
259                                          String   clientKeystoreType)
260             throws NamingException
261     {
262      return openContext(version,
263                 url,
264                 userDN,
265                 pwd,
266                 tracing,
267                 referralType,
268                 aliasType,
269                 useSSL,
270                 cacerts,
271                 clientcerts,
272                 caKeystorePwd,
273                 clientKeystorePwd,
274                 caKeystoreType,
275                 clientKeystoreType,
276                 false);
277     }
278 
279     /**
280      * This static ftn. can be used to open an initial context (which can then
281      * be used to construct a BasicOps object).  Note that this ftn may take some
282      * time to return...
283      *
284      * @param version            the LDAP Version (2 or 3) being used.
285      * @param url                a url of the form ldap://hostname:portnumber.
286      * @param userDN             the Manager User's distinguished name (optionally null if not used).
287      * @param pwd                the Manager User's password - (is null if user is not manager).
288      * @param tracing            whether to set BER tracing on or not.
289      * @param referralType       the jndi ldap referral type: [follow:ignore:throw] (may be null - defaults to 'follow').
290      * @param aliasType          how aliases should be handled in searches ('always'|'never'|'find'|'search').
291      * @param useSSL             whether to use SSL (either simple or client-authenticated).
292      * @param cacerts            the file containing the trusted server certificates (no keys).
293      * @param clientcerts        the file containing client certificates.
294      * @param caKeystorePwd      the password to the ca's keystore (may be null for non-client authenticated ssl).
295      * @param clientKeystorePwd  the password to the client's keystore (may be null for non-client authenticated ssl).
296      * @param caKeystoreType     the type of keystore file; e.g. 'JKS', or 'PKCS12'.
297      * @param clientKeystoreType the type of keystore file; e.g. 'JKS', or 'PKCS12'.
298      * @param useGSSAPI          use GSSAPI (usually with kerberos)
299      * @return The created context.
300      */
301 
302     public static DirContext openContext(int version,
303                                          String   url,
304                                          String   userDN,
305                                          char[] pwd,
306                                          boolean tracing,
307                                          String   referralType,
308                                          String   aliasType,
309                                          boolean useSSL,
310                                          String   cacerts,
311                                          String   clientcerts,
312                                          char[] caKeystorePwd,
313                                          char[] clientKeystorePwd,
314                                          String   caKeystoreType,
315                                          String   clientKeystoreType,
316                                          boolean useGSSAPI)
317             throws NamingException
318     {
319         ConnectionData connectionData =
320                 new ConnectionData(version,
321                         url,
322                         userDN,
323                         pwd,
324                         tracing,
325                         referralType,
326                         aliasType,
327                         useSSL,
328                         cacerts,
329                         clientcerts,
330                         caKeystorePwd,
331                         clientKeystorePwd,
332                         caKeystoreType,
333                         clientKeystoreType,
334                         useGSSAPI, null);
335 
336         return JNDIOps.openContext(connectionData.getJNDIEnvironment());
337     }
338 
339 
340     /**
341      * This is a raw interface to javax.naming.directory.InitialDirContext, that allows
342      * an arbitrary environment string to be passed through.  Often the other version
343      * of openContext() above will prove more convenient.
344      *
345      * @param env a list of environment variables for the context
346      * @return a newly created DirContext.
347      */
348 
349     public static DirContext openContext(Properties   env)
350             throws NamingException
351     {
352         log.fine("opening Directory Context to " + env.get(Context.PROVIDER_URL) + "\n using: " + env.get(Context.INITIAL_CONTEXT_FACTORY));
353 
354         DirContext ctx = new InitialDirContext(env);
355 
356         log.fine("context successfully opened " + (ctx != null));
357 
358         if (ctx != null)
359         {
360 
361         }
362         return ctx;
363     }
364 
365     private void setLdapVersion(Hashtable   env) throws NamingException
366     {
367         try
368         {
369             ldapVersion = Integer.parseInt(env.get("java.naming.ldap.version").toString());
370         }
371         catch (Exception   e)
372         {
373             throw new NamingException("BasicOps.openContext(): unable to determine ldap version of connection.");
374         }
375     }
376 
377 
378     /**
379      * A simple wrapper for a ctx.getSchema("") call.
380      *
381      * @deprecated - jndi's 'getSchema' may not always be available (e.g. not implemented in dsml).
382      *             use 'getSchemaAttributes()' instead
383      */
384 
385     public DirContext getSchema() throws NamingException
386     {
387         if (getContext() == null)
388             throw new NamingException("No context open to retrieve Schema from");
389 
390         log.finest("getSchema() call");
391 
392         return getContext().getSchema("");
393     }
394 
395     /**
396      * basically a wrapper for context.rename... changes the
397      * distinguished name of an object, checks for error.
398      *
399      * @param OldDN current distinguished name of an object.
400      * @param NewDN the name it is to be changed to.
401      * @deprecated use renameEntry instead
402      */
403 
404 //XXXX - this will fail for single valued manditory attributes.
405 //XXXX - since using 'deleteRDN = false' - 30 May 2002.
406 
407     public void renameObject(Name OldDN, Name NewDN)
408             throws NamingException
409     {
410         renameEntry(OldDN, NewDN);
411     }
412 
413 
414     /**
415      * Copies an object to a new DN by the simple expedient of adding
416      * an object with the new DN, and the attributes of the old object.
417      *
418      * @param FromDN the original object being copied
419      * @param ToDN   the new object being created
420      * @deprecated use copyEntry instead
421      */
422 
423     public void copyObject(Name FromDN, Name ToDN)
424             throws NamingException
425     {
426         copyEntry(FromDN, ToDN);
427     }
428 
429 
430 
431     /**
432      * creates a new object (subcontext) with the given
433      * dn and attributes.
434      *
435      * @param Dn   the distinguished name of the new object
436      * @param atts attributes for the new object
437      * @deprecated use addEntry instead
438      */
439 
440     public void addObject(Name Dn, Attributes atts)
441             throws NamingException
442     {
443         addEntry(Dn, atts);
444     }
445 
446     /**
447      * deletes a leaf entry (subcontext).  It is
448      * an error to attempt to delete an entry which is not a leaf
449      * entry, i.e. which has children.
450      *
451      * @deprecated use deleteEntry instead
452      */
453 
454     public void deleteObject(Name Dn)
455             throws NamingException
456     {
457         deleteEntry(Dn);
458     }
459 
460     /**
461      * Updates an object with a new set of attributes
462      *
463      * @param Dn   distinguished name of object to update
464      * @param atts the new attributes to update the object with.
465      * @deprecated use updateEntry instead
466      */
467 
468     public void updateObject(Name Dn, Attributes atts)
469             throws NamingException
470     {
471         updateEntry(Dn, atts);
472     }
473 
474 
475 
476     /**
477      * Performs a base object search (i.e. just a search of the current entry, nothing below it),
478      * returning no attributes (i.e. just DNs);
479      *
480      * @param Searchbase the domain name (relative to initial context in ldap) to seach from.
481      * @param filter     the non-null filter to use for the search
482      * @param limit      the maximum number of results to return
483      * @param timeout    the maximum time to wait before abandoning the search
484      * @return list of search results ('SearchResult's); entries matching the search filter.
485      * @deprecated use searchBaseEntry instead
486      */
487 
488     public NamingEnumeration searchBaseObject(Name Searchbase, String   filter, int limit, int timeout)
489             throws NamingException
490     {
491         return searchBaseEntry(Searchbase, filter, limit, timeout, new String  []{"objectClass"});
492     }
493 
494 
495     /**
496      * Performs a base object search (i.e. just a search of the current entry, nothing below it).
497      *
498      * @param Searchbase       the domain name (relative to initial context in ldap) to seach from.
499      * @param filter           the non-null filter to use for the search
500      * @param limit            the maximum number of results to return
501      * @param timeout          the maximum time to wait before abandoning the search
502      * @param returnAttributes an array of strings containing the names of attributes to search. (null = all, empty array = none)
503      * @return list of search results ('SearchResult's); entries matching the search filter.
504      * @deprecated use searchBaseEntry instead
505      */
506 
507     public NamingEnumeration searchBaseObject(Name Searchbase, String   filter, int limit,
508                                               int timeout, String  [] returnAttributes)
509             throws NamingException
510     {
511         return searchBaseEntry(Searchbase, filter, limit, timeout, returnAttributes);
512     }
513 
514 
515     /**
516      * Shuts down the current context.<p>
517      * nb. It is not an error to call this method multiple times.
518      */
519 
520     public void close()
521             throws NamingException
522     {
523         super.close();
524 
525         log.fine("closing context");
526 
527         ldapVersion = -1;
528     }
529 
530     /**
531      * This picks up the name parser used at the root level... if
532      * the context only spans a single name space (i.e. for an ldap
533      * directory) this will be the same as the one used throughout.
534      */
535 
536     public NameParser getBaseNameParser()
537             throws NamingException
538     {
539         log.finer("getting base name parser");
540 
541         if (getContext() == null)
542             throw new NamingException("Null Directory Context\n  in BasicOps.searchSubTree()\n  (so can't do anything!)");
543 
544         return getContext().getNameParser("");
545     }
546 
547     /**
548      * Returns the ldap version of the current connection
549      */
550 
551     public int getLdapVersion()
552     {
553         return ldapVersion;
554     }
555 
556 }
557
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags