View Javadoc
1   /*
2    * Copyright (c) 1999, 2000, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.naming.directory;
27  
28  import javax.naming.Binding;
29  
30  /**
31    * This class represents an item in the NamingEnumeration returned as a
32    * result of the DirContext.search() methods.
33    *<p>
34    * A SearchResult instance is not synchronized against concurrent
35    * multithreaded access. Multiple threads trying to access and modify
36    * a single SearchResult instance should lock the object.
37    *
38    * @author Rosanna Lee
39    * @author Scott Seligman
40    *
41    * @see DirContext#search
42    * @since 1.3
43    */
44  
45  public class SearchResult extends Binding {
46      /**
47       * Contains the attributes returned with the object.
48       * @serial
49       */
50      private Attributes attrs;
51  
52      /**
53        * Constructs a search result using the result's name, its bound object, and
54        * its attributes.
55        *<p>
56        * <tt>getClassName()</tt> will return the class name of <tt>obj</tt>
57        * (or null if <tt>obj</tt> is null) unless the class name has been
58        * explicitly set using <tt>setClassName()</tt>.
59        *
60        * @param name The non-null name of the search item. It is relative
61        *             to the <em>target context</em> of the search (which is
62        * named by the first parameter of the <code>search()</code> method)
63        *
64        * @param obj  The object bound to name. Can be null.
65        * @param attrs The attributes that were requested to be returned with
66        * this search item. Cannot be null.
67        * @see javax.naming.NameClassPair#setClassName
68        * @see javax.naming.NameClassPair#getClassName
69        */
70      public SearchResult(String name, Object obj, Attributes attrs) {
71          super(name, obj);
72          this.attrs = attrs;
73      }
74  
75      /**
76        * Constructs a search result using the result's name, its bound object, and
77        * its attributes, and whether the name is relative.
78        *<p>
79        * <tt>getClassName()</tt> will return the class name of <tt>obj</tt>
80        * (or null if <tt>obj</tt> is null) unless the class name has been
81        * explicitly set using <tt>setClassName()</tt>
82        *
83        * @param name The non-null name of the search item.
84        * @param obj  The object bound to name. Can be null.
85        * @param attrs The attributes that were requested to be returned with
86        * this search item. Cannot be null.
87        * @param isRelative true if <code>name</code> is relative
88        *         to the target context of the search (which is named by
89        *         the first parameter of the <code>search()</code> method);
90        *         false if <code>name</code> is a URL string.
91        * @see javax.naming.NameClassPair#setClassName
92        * @see javax.naming.NameClassPair#getClassName
93        */
94      public SearchResult(String name, Object obj, Attributes attrs,
95          boolean isRelative) {
96          super(name, obj, isRelative);
97          this.attrs = attrs;
98      }
99  
100     /**
101       * Constructs a search result using the result's name, its class name,
102       * its bound object, and its attributes.
103       *
104       * @param name The non-null name of the search item. It is relative
105       *             to the <em>target context</em> of the search (which is
106       * named by the first parameter of the <code>search()</code> method)
107       *
108       * @param  className       The possibly null class name of the object
109       *         bound to <tt>name</tt>. If null, the class name of <tt>obj</tt> is
110       *         returned by <tt>getClassName()</tt>. If <tt>obj</tt> is also null,
111       *         <tt>getClassName()</tt> will return null.
112       * @param obj  The object bound to name. Can be null.
113       * @param attrs The attributes that were requested to be returned with
114       * this search item. Cannot be null.
115       * @see javax.naming.NameClassPair#setClassName
116       * @see javax.naming.NameClassPair#getClassName
117       */
118     public SearchResult(String name, String className,
119         Object obj, Attributes attrs) {
120         super(name, className, obj);
121         this.attrs = attrs;
122     }
123 
124     /**
125       * Constructs a search result using the result's name, its class name,
126       * its bound object, its attributes, and whether the name is relative.
127       *
128       * @param name The non-null name of the search item.
129       * @param  className       The possibly null class name of the object
130       *         bound to <tt>name</tt>. If null, the class name of <tt>obj</tt> is
131       *         returned by <tt>getClassName()</tt>. If <tt>obj</tt> is also null,
132       *         <tt>getClassName()</tt> will return null.
133       * @param obj  The object bound to name. Can be null.
134       * @param attrs The attributes that were requested to be returned with
135       * this search item. Cannot be null.
136       * @param isRelative true if <code>name</code> is relative
137       *         to the target context of the search (which is named by
138       *         the first parameter of the <code>search()</code> method);
139       *         false if <code>name</code> is a URL string.
140       * @see javax.naming.NameClassPair#setClassName
141       * @see javax.naming.NameClassPair#getClassName
142       */
143     public SearchResult(String name, String className, Object obj,
144         Attributes attrs, boolean isRelative) {
145         super(name, className, obj, isRelative);
146         this.attrs = attrs;
147     }
148 
149     /**
150      * Retrieves the attributes in this search result.
151      *
152      * @return The non-null attributes in this search result. Can be empty.
153      * @see #setAttributes
154      */
155     public Attributes getAttributes() {
156         return attrs;
157     }
158 
159 
160     /**
161      * Sets the attributes of this search result to <code>attrs</code>.
162      * @param attrs The non-null attributes to use. Can be empty.
163      * @see #getAttributes
164      */
165     public void setAttributes(Attributes attrs) {
166         this.attrs = attrs;
167         // ??? check for null?
168     }
169 
170 
171     /**
172       * Generates the string representation of this SearchResult.
173       * The string representation consists of the string representation
174       * of the binding and the string representation of
175       * this search result's attributes, separated by ':'.
176       * The contents of this string is useful
177       * for debugging and is not meant to be interpreted programmatically.
178       *
179       * @return The string representation of this SearchResult. Cannot be null.
180       */
181     public String toString() {
182         return super.toString() + ":" + getAttributes();
183     }
184 
185     /**
186      * Use serialVersionUID from JNDI 1.1.1 for interoperability
187      */
188     private static final long serialVersionUID = -9158063327699723172L;
189 }