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 2010 Sun Microsystems, Inc.
025 *      Portions copyright 2012 ForgeRock AS.
026 */
027package org.forgerock.opendj.ldap.controls;
028
029import org.forgerock.opendj.ldap.ByteString;
030
031import org.forgerock.util.Reject;
032
033/**
034 * A generic control which can be used to represent arbitrary raw request and
035 * response controls.
036 */
037public final class GenericControl implements Control {
038
039    /**
040     * Creates a new control having the same OID, criticality, and value as the
041     * provided control.
042     *
043     * @param control
044     *            The control to be copied.
045     * @return The new control.
046     * @throws NullPointerException
047     *             If {@code control} was {@code null}.
048     */
049    public static GenericControl newControl(final Control control) {
050        Reject.ifNull(control);
051
052        if (control instanceof GenericControl) {
053            return (GenericControl) control;
054        }
055
056        return new GenericControl(control.getOID(), control.isCritical(), control.getValue());
057    }
058
059    /**
060     * Creates a new non-critical control having the provided OID and no value.
061     *
062     * @param oid
063     *            The numeric OID associated with this control.
064     * @return The new control.
065     * @throws NullPointerException
066     *             If {@code oid} was {@code null}.
067     */
068    public static GenericControl newControl(final String oid) {
069        return new GenericControl(oid, false, null);
070    }
071
072    /**
073     * Creates a new control having the provided OID and criticality, but no
074     * value.
075     *
076     * @param oid
077     *            The numeric OID associated with this control.
078     * @param isCritical
079     *            {@code true} if it is unacceptable to perform the operation
080     *            without applying the semantics of this control, or
081     *            {@code false} if it can be ignored.
082     * @return The new control.
083     * @throws NullPointerException
084     *             If {@code oid} was {@code null}.
085     */
086    public static GenericControl newControl(final String oid, final boolean isCritical) {
087        return new GenericControl(oid, isCritical, null);
088    }
089
090    /**
091     * Creates a new control having the provided OID, criticality, and value.
092     * <p>
093     * If {@code value} is not an instance of {@code ByteString} then it will be
094     * converted using the {@link ByteString#valueOf(Object)} method.
095     *
096     * @param oid
097     *            The numeric OID associated with this control.
098     * @param isCritical
099     *            {@code true} if it is unacceptable to perform the operation
100     *            without applying the semantics of this control, or
101     *            {@code false} if it can be ignored.
102     * @param value
103     *            The value associated with this control, or {@code null} if
104     *            there is no value. Its format is defined by the specification
105     *            of this control.
106     * @return The new control.
107     * @throws NullPointerException
108     *             If {@code oid} was {@code null}.
109     */
110    public static GenericControl newControl(final String oid, final boolean isCritical,
111            final Object value) {
112        return new GenericControl(oid, isCritical, (value == null) ? null : ByteString
113                .valueOf(value));
114    }
115
116    private final String oid;
117
118    private final boolean isCritical;
119
120    private final ByteString value;
121
122    /** Prevent direct instantiation. */
123    private GenericControl(final String oid, final boolean isCritical, final ByteString value) {
124        Reject.ifNull(oid);
125        this.oid = oid;
126        this.isCritical = isCritical;
127        this.value = value;
128    }
129
130    /** {@inheritDoc} */
131    public String getOID() {
132        return oid;
133    }
134
135    /** {@inheritDoc} */
136    public ByteString getValue() {
137        return value;
138    }
139
140    /** {@inheritDoc} */
141    public boolean hasValue() {
142        return value != null;
143    }
144
145    /** {@inheritDoc} */
146    public boolean isCritical() {
147        return isCritical;
148    }
149
150    /** {@inheritDoc} */
151    @Override
152    public String toString() {
153        final StringBuilder builder = new StringBuilder();
154        builder.append("Control(oid=");
155        builder.append(getOID());
156        builder.append(", criticality=");
157        builder.append(isCritical());
158        if (value != null) {
159            builder.append(", value=");
160            builder.append(value.toHexPlusAsciiString(4));
161        }
162        builder.append(")");
163        return builder.toString();
164    }
165
166}