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