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 legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2006-2009 Sun Microsystems, Inc.
025 *      Portions Copyright 2014 ForgeRock AS
026 */
027package org.opends.server.types;
028
029import org.forgerock.opendj.io.ASN1Writer;
030
031import java.io.IOException;
032
033
034/**
035 * This class defines a data structure that holds information about a
036 * control that can be included in a request or response.
037 */
038@org.opends.server.types.PublicAPI(
039     stability=org.opends.server.types.StabilityLevel.UNCOMMITTED,
040     mayInstantiate=true,
041     mayExtend=true,
042     mayInvoke=true)
043public abstract class Control
044{
045  /** The criticality for this control. */
046  private boolean isCritical;
047
048  /** The OID for this control. */
049  private String oid;
050
051
052
053  /**
054   * Creates a new control with no value.
055   *
056   * @param  oid         The OID for this control.
057   * @param  isCritical  Indicates whether this control should be
058   *                     considered critical in processing the
059   *                     request.
060   */
061  protected Control(String oid, boolean isCritical)
062  {
063    this.oid        = oid;
064    this.isCritical = isCritical;
065  }
066
067
068
069  /**
070   * Retrieves the OID for this control.
071   *
072   * @return  The OID for this control.
073   */
074  public final String getOID()
075  {
076    return oid;
077  }
078
079
080  /**
081   * Indicates whether this control should be considered critical in
082   * processing the request.
083   *
084   * @return  <CODE>true</CODE> if this code should be considered
085   *          critical, or <CODE>false</CODE> if not.
086   */
087  public final boolean isCritical()
088  {
089    return isCritical;
090  }
091
092
093
094  /**
095   * Retrieves a string representation of this control.
096   *
097   * @return  A string representation of this control.
098   */
099  @Override
100  public final String toString()
101  {
102    StringBuilder buffer = new StringBuilder();
103    toString(buffer);
104    return buffer.toString();
105  }
106
107  /**
108   * Writes this control to an ASN.1 writer.
109   *
110   * @param writer The ASN.1 writer to use.
111   * @throws IOException If a problem occurs while writing to the
112   *                     stream.
113   */
114  public final void write(ASN1Writer writer) throws IOException
115  {
116    writer.writeStartSequence();
117    writer.writeOctetString(getOID());
118    if(isCritical())
119    {
120      writer.writeBoolean(isCritical());
121    }
122    writeValue(writer);
123    writer.writeEndSequence();
124  }
125
126  /**
127   * Writes this control's value to an ASN.1 writer. The value
128   * (if any) must be written as an ASN1OctetString.
129   *
130   * @param writer The ASN.1 writer to use.
131   * @throws IOException If a problem occurs while writing to the
132   *                     stream.
133   */
134  protected abstract void writeValue(ASN1Writer writer)
135      throws IOException;
136
137
138
139  /**
140   * Appends a string representation of this control to the provided
141   * buffer.
142   *
143   * @param  buffer  The buffer to which the information should be
144   *                 appended.
145   */
146  public void toString(StringBuilder buffer)
147  {
148    buffer.append("Control(oid=");
149    buffer.append(oid);
150    buffer.append(",isCritical=");
151    buffer.append(isCritical);
152    buffer.append(")");
153  }
154}
155