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 2015 ForgeRock AS
025 */
026package org.opends.server.controls;
027
028import static org.opends.server.util.ServerConstants.OID_TRANSACTION_ID_CONTROL;
029
030import java.io.IOException;
031
032import org.forgerock.opendj.io.ASN1Writer;
033import org.forgerock.opendj.ldap.ByteString;
034import org.forgerock.opendj.ldap.ResultCode;
035import org.opends.messages.ProtocolMessages;
036import org.opends.server.types.Control;
037import org.opends.server.types.DirectoryException;
038
039/**
040 * Control that provides a transaction ID.
041 * <p>
042 * The transaction ID is related to Common Audit : it is used for tracking the
043 * processing of a user-interaction as it passes through the Forgerock stack
044 * <p>
045 * The control's value is the UTF-8 encoding of the transaction ID.
046 */
047public class TransactionIdControl extends Control
048{
049  /** ControlDecoder implementation to decode this control from a ByteString. */
050  private static final class Decoder implements ControlDecoder<TransactionIdControl>
051  {
052    @Override
053    public TransactionIdControl decode(boolean isCritical, ByteString value) throws DirectoryException
054    {
055      if (value == null)
056      {
057        throw new DirectoryException(ResultCode.PROTOCOL_ERROR,
058            ProtocolMessages.ERR_TRANSACTION_ID_CONTROL_HAS_NO_VALUE.get());
059      }
060      return new TransactionIdControl(isCritical, value.toString());
061    }
062
063
064    @Override
065    public String getOID()
066    {
067      return OID_TRANSACTION_ID_CONTROL;
068    }
069
070  }
071
072  /** The Control Decoder that can be used to decode this control. */
073  public static final ControlDecoder<TransactionIdControl> DECODER = new Decoder();
074
075  /** The id value of this control. */
076  private final String transactionId;
077
078  /**
079   * Creates a new Transaction Id Control.
080   *
081   * @param  isCritical  Indicates whether this control should be considered
082   *                     critical to the operation processing.
083   * @param  transactionId The id to pass through this control.
084   */
085  public TransactionIdControl(boolean isCritical, String transactionId)
086  {
087    super(OID_TRANSACTION_ID_CONTROL, isCritical);
088    this.transactionId = transactionId;
089  }
090
091  /**
092   * Writes this control's value to an ASN.1 writer. The value (if any) must be
093   * written as an ASN1OctetString.
094   *
095   * @param writer
096   *          The ASN.1 output stream to write to.
097   * @throws IOException
098   *           If a problem occurs while writing to the stream.
099   */
100  @Override
101  public void writeValue(ASN1Writer writer) throws IOException
102  {
103    writer.writeOctetString(transactionId);
104  }
105
106  /**
107   * Retrieves the transaction id associated with this control.
108   *
109   * @return  The transaction id associated with this control.
110   */
111  public String getTransactionId()
112  {
113    return transactionId;
114  }
115
116  /**
117   * Appends a string representation of this control to the provided buffer.
118   *
119   * @param buffer
120   *          The buffer to which the information should be appended.
121   */
122  @Override
123  public void toString(StringBuilder buffer)
124  {
125    buffer.append("TransactionIdControl(id=");
126    buffer.append(transactionId);
127    buffer.append(")");
128  }
129}