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 2014 ForgeRock AS.
015 */
016
017package org.forgerock.openig.audit;
018
019import static java.util.Collections.*;
020import static org.forgerock.util.Reject.*;
021
022import java.util.Collection;
023import java.util.LinkedHashSet;
024import java.util.Set;
025
026import org.forgerock.openig.http.Exchange;
027
028/**
029 * An AuditEvent represents a point in time during the processing of an Exchange.
030 * <p>
031 * Instances of this class are <b>not thread-safe</b>: any filter can possibly update the {@link Exchange} while
032 * processing the audit event. Special care must be taken when dealing with the Exchange.
033 * <p>
034 * The {@literal source} property helps to identify the object that emitted the notification.
035 * The {@literal timestamp} property gives a time marker to keep events organized in a
036 * sequential manner (expressed in milliseconds).
037 * The {@literal exchange} property gives a pointer to the captured {@link Exchange} (never {@code null}). There is
038 * no way to guarantee, if the notification is processed in an asynchronous way, that the exchange content was not
039 * modified in the meantime.
040 * The {@literal tags} property helps to qualify this notification (no duplicated values).
041 */
042public final class AuditEvent {
043    private final AuditSource source;
044    private final long timestamp;
045    private final Exchange exchange;
046    private final Set<String> tags = new LinkedHashSet<String>();
047
048    /**
049     * Builds a new AuditEvent with provided values.
050     *
051     * @param source
052     *         source of the event (never {@code null})
053     * @param timestamp
054     *         creation date of the notification (expressed in milliseconds)
055     * @param exchange
056     *         captured exchange (never {@code null})
057     * @param tags
058     *         qualifiers (never {@code null})
059     */
060    public AuditEvent(final AuditSource source,
061                      final long timestamp,
062                      final Exchange exchange,
063                      final Collection<String> tags) {
064        this.source = checkNotNull(source);
065        this.timestamp = timestamp;
066        this.exchange = checkNotNull(exchange);
067        this.tags.addAll(checkNotNull(tags));
068    }
069
070    /**
071     * Returns the source of the audit event (never {@code null}).
072     *
073     * @return the source of the audit event (never {@code null}).
074     */
075    public AuditSource getSource() {
076        return source;
077    }
078
079    /**
080     * Returns the timestamp of this event (expressed in milliseconds).
081     *
082     * @return the timestamp of this event (expressed in milliseconds).
083     */
084    public long getTimestamp() {
085        return timestamp;
086    }
087
088    /**
089     * Returns the captured {@link Exchange} (never {@code null}).
090     * Notice that this is a pointer to the being processed exchange (a live object, not a copy), so, if this event
091     * is processed asynchronously, the exchange content may have changed.
092     *
093     * @return the captured {@link Exchange} (never {@code null}).
094     */
095    public Exchange getExchange() {
096        return exchange;
097    }
098
099    /**
100     * Returns an immutable set of event's qualifiers (never {@code null}).
101     *
102     * @return an immutable set of event's qualifiers (never {@code null}).
103     */
104    public Set<String> getTags() {
105        return unmodifiableSet(tags);
106    }
107}