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}