001    /*
002     * CDDL HEADER START
003     *
004     * The contents of this file are subject to the terms of the
005     * Common Development and Distribution License, Version 1.0 only
006     * (the "License").  You may not use this file except in compliance
007     * with the License.
008     *
009     * You can obtain a copy of the license at
010     * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011     * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
012     * See the License for the specific language governing permissions
013     * and limitations under the License.
014     *
015     * When distributing Covered Code, include this CDDL HEADER in each
016     * file and include the License file at
017     * trunk/opends/resource/legal-notices/OpenDS.LICENSE.  If applicable,
018     * add the following below this CDDL HEADER, with the fields enclosed
019     * by brackets "[]" replaced with your own identifying information:
020     *      Portions Copyright [yyyy] [name of copyright owner]
021     *
022     * CDDL HEADER END
023     *
024     *
025     *      Copyright 2006-2008 Sun Microsystems, Inc.
026     */
027    package org.opends.server.types;
028    
029    
030    
031    import java.util.ArrayList;
032    import java.util.List;
033    import java.util.Iterator;
034    
035    
036    
037    
038    /**
039     * This class defines a data structure for storing information about a
040     * referral returned while processing a search request.
041     */
042    @org.opends.server.types.PublicAPI(
043         stability=org.opends.server.types.StabilityLevel.UNCOMMITTED,
044         mayInstantiate=false,
045         mayExtend=false,
046         mayInvoke=true)
047    public final class SearchResultReference
048    {
049      // The set of controls associated with this search result reference.
050      private List<Control> controls;
051    
052      // The set of referral URLs for this search result reference.
053      private List<String> referralURLs;
054    
055    
056    
057      /**
058       * Creates a new search result reference with the provided referral
059       * URL.
060       *
061       * @param  referralURL  The referral URL for this search result
062       *                      reference.
063       */
064      public SearchResultReference(String referralURL)
065      {
066        referralURLs = new ArrayList<String>(1);
067        referralURLs.add(referralURL);
068    
069        this.controls = new ArrayList<Control>(0);
070      }
071    
072    
073    
074      /**
075       * Creates a new search result reference with the provided set of
076       * referral URLs and no controls.
077       *
078       * @param  referralURLs  The referral URLs for this search result
079       *                       reference.
080       */
081      public SearchResultReference(List<String> referralURLs)
082      {
083        if (referralURLs == null)
084        {
085          this.referralURLs = new ArrayList<String>();
086        }
087        else
088        {
089          this.referralURLs = referralURLs;
090        }
091    
092        this.controls = new ArrayList<Control>(0);
093      }
094    
095    
096    
097      /**
098       * Creates a new search result reference with the provided set of
099       * referral URLs and no controls.
100       *
101       * @param  referralURLs  The referral URLs for this search result
102       *                       reference.
103       * @param  controls      The set of controls for this search result
104       *                       reference.
105       */
106      public SearchResultReference(List<String> referralURLs,
107                                   List<Control> controls)
108      {
109        if (referralURLs == null)
110        {
111          this.referralURLs = new ArrayList<String>();
112        }
113        else
114        {
115          this.referralURLs = referralURLs;
116        }
117    
118        if (controls == null)
119        {
120          this.controls = new ArrayList<Control>(0);
121        }
122        else
123        {
124          this.controls = controls;
125        }
126      }
127    
128    
129    
130      /**
131       * Retrieves the set of referral URLs for this search result
132       * reference.  It may be modified by the caller.
133       *
134       * @return  The set of referral URLs for this search result
135       *          reference.
136       */
137      public List<String> getReferralURLs()
138      {
139        return referralURLs;
140      }
141    
142    
143    
144      /**
145       * Retrieves a string representation of the referral URL(s) for this
146       * search result reference.
147       *
148       * @return  A string representation of the referral URL(s) for this
149       *          search result reference.
150       */
151      public String getReferralURLString()
152      {
153        if ((referralURLs == null) || (referralURLs.isEmpty()))
154        {
155          return "";
156        }
157        else if (referralURLs.size() == 1)
158        {
159          return referralURLs.get(0);
160        }
161        else
162        {
163          Iterator<String> iterator = referralURLs.iterator();
164          StringBuilder    buffer   = new StringBuilder();
165          buffer.append("{ ");
166          buffer.append(iterator.next());
167    
168          while (iterator.hasNext())
169          {
170            buffer.append(", ");
171            buffer.append(iterator.next());
172          }
173    
174          buffer.append(" }");
175          return buffer.toString();
176        }
177      }
178    
179    
180    
181      /**
182       * Retrieves the set of controls to include with this search result
183       * reference when it is sent to the client.  This set may be
184       * modified by the caller.
185       *
186       * @return  The set of controls to include with this search result
187       *          reference when it is sent to the client.
188       */
189      public List<Control> getControls()
190      {
191        return controls;
192      }
193    }
194