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