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 2015 ForgeRock AS.
015 */
016package org.forgerock.services;
017
018import static org.forgerock.json.JsonValue.field;
019import static org.forgerock.json.JsonValue.json;
020import static org.forgerock.json.JsonValue.object;
021
022import java.util.concurrent.atomic.AtomicInteger;
023
024import org.forgerock.json.JsonValue;
025import org.forgerock.util.Reject;
026import org.forgerock.util.generator.IdGenerator;
027
028/**
029 * TransactionId value should be unique per request coming from an external agent so that all events occurring in
030 * response to the same external stimulus can be tied together.
031 *
032 * Calls to external systems should propagate the value returned by {@link #createSubTransactionId()} so that Audit
033 * events reported by the external system can also be tied back to the original stimulus.
034 *
035 * Due to the fact that each TransactionId instance creates a sequence of sub-transaction IDs, the same TransactionId
036 * object should be used while fulfilling a given request; it is not appropriate to create multiple instances of
037 * TransactionId with the same value as this would lead to duplicate sub-transaction ID values. As such, two instances
038 * of TransactionId with the same value are not considered equal.
039 *
040 * This class is thread-safe.
041 *
042 * @since 2.0
043 */
044public final class TransactionId {
045
046    private final String value;
047    private final AtomicInteger subTransactionIdCounter;
048
049    /**
050     * Construct a {@code TransactionId} with a random value.
051     */
052    public TransactionId() {
053        this(IdGenerator.DEFAULT.generate());
054    }
055
056    /**
057     * Construct a {@code TransactionId} with the specified value. The value must not be null nor empty.
058     *
059     * @param value The value to initialize the transactionId from.
060     */
061    public TransactionId(String value) {
062        this(value, 0);
063    }
064
065    /**
066     * Construct a {@code TransactionId} with the specified value.
067     */
068    private TransactionId(String value, int counter) {
069        Reject.ifTrue(value == null || value.isEmpty(), "The value must not be null nor empty.");
070        this.value = value;
071        this.subTransactionIdCounter = new AtomicInteger(counter);
072    }
073
074    /**
075     * Returns the value of this TransactionId.
076     * @return Non-null, {@code TransactionId} value.
077     */
078    public String getValue() {
079        return value;
080    }
081
082    /**
083     * Creates a new TransactionId, child of this one.
084     * @return Non-null, {@code TransactionId} value that can be passed to an external system.
085     */
086    public TransactionId createSubTransactionId() {
087        final String subTransactionId = value + "/" + subTransactionIdCounter.getAndIncrement();
088        return new TransactionId(subTransactionId);
089    }
090
091    /**
092     * Returns a representation of this TransactionId as a JsonValue.
093     * The JsonValue will be composed of 2 fields : value and subTransactionIdCounter.
094     * @return a representation of this TransactionId as a JsonValue.
095     */
096    public JsonValue toJson() {
097        return json(object(field("value", value), field("subTransactionIdCounter", subTransactionIdCounter.get())));
098    }
099
100    /**
101     * Creates a TransactionId from a JsonValue.
102     * @param value the JsonValue used to create the TransactionId, composed of 2 fields : value and
103     * subTransactionIdCounter.
104     * @return a TransactionId initialized with the values provided by the JsonValue.
105     */
106    public static TransactionId valueOf(JsonValue value) {
107        return new TransactionId(value.get("value").required().asString(),
108                value.get("subTransactionIdCounter").required().asInteger());
109    }
110
111}