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 */
016
017package org.forgerock.audit.events;
018
019import org.forgerock.json.JsonPointer;
020import org.forgerock.json.JsonValue;
021import org.forgerock.json.resource.InternalServerErrorException;
022import org.forgerock.json.resource.ResourceException;
023
024import java.util.List;
025
026/**
027 * Helper methods for AuditEvents.
028 */
029public final class AuditEventHelper {
030
031    private static final String PROPERTIES = "properties";
032
033    /** Json String value type. */
034    public static final String STRING_TYPE = "string";
035    /** Json Object value type. */
036    public static final String OBJECT_TYPE = "object";
037    /** Json boolean value type. */
038    public static final String BOOLEAN_TYPE = "boolean";
039    /** Json number value type. */
040    public static final String NUMBER_TYPE = "number";
041    /** Json array value type. */
042    public static final String ARRAY_TYPE = "array";
043
044    private static final String TYPE = "type";
045    private static final String SCHEMA = "schema";
046    private static final String REQUIRED = "required";
047    private static final String LOG_TO = "logTo";
048
049    private AuditEventHelper() {
050
051    }
052
053    /**
054     * Gets whether a AuditEvent property is required.
055     * @param auditEvent the audit event to get the property of.
056     * @param property the property to check if required.
057     * @return true if the property is required; false otherwise.
058     */
059    public static boolean isPropertyRequired(final JsonValue auditEvent, final JsonPointer property) {
060        return auditEvent.get(SCHEMA).get(PROPERTIES).get(property).get(REQUIRED).defaultTo(false).asBoolean();
061    }
062
063    /**
064     * Gets a AuditEvent property type.
065     * @param auditEvent the audit event to get the property of.
066     * @param property the property to check if required.
067     * @return true if the property is required; false otherwise.
068     * @throws org.forgerock.json.resource.ResourceException if the property is unknown
069     */
070    public static String getPropertyType(final JsonValue auditEvent, final JsonPointer property)
071            throws ResourceException {
072
073        final String[] pointers  = property.toArray();
074        JsonValue properties = auditEvent.get(SCHEMA);
075        for (final String pointer : pointers) {
076            properties = properties.get(PROPERTIES).get(pointer);
077            if (properties == null || properties.isNull()) {
078                throw new InternalServerErrorException("Unknown audit event property: " + property.toString());
079            }
080        }
081        return properties.get(TYPE).asString();
082    }
083
084    /**
085     * Gets the AuditEventHandlers that the audit event is configure to log to.
086     * @param auditEvent the audit event JsonValue definition.
087     * @return List of audit event handler names to log to.
088     */
089    public static List<String> getConfiguredAuditEventHandlers(final JsonValue auditEvent) {
090        return auditEvent.get(LOG_TO).asList(String.class);
091    }
092
093    /**
094     * Gets the Audit Event schema properties.
095     * @param auditEvent the audit event JsonValue definition.
096     * @return JsonValue containing all the properties for the audit event.
097     * @throws ResourceException if no audit event is defined
098     */
099    public static JsonValue getAuditEventProperties(final JsonValue auditEvent) throws ResourceException {
100        if (auditEvent == null || auditEvent.isNull()) {
101            throw new InternalServerErrorException("Can't get properties for an undefined audit event");
102        }
103        return auditEvent.get(SCHEMA).get(PROPERTIES);
104    }
105
106    /**
107     * Gets the Audit Event schema.
108     * @param auditEvent the audit event JsonValue definition.
109     * @return JsonValue containing the schema object for the audit event.
110     * @throws ResourceException if no audit event is defined
111     */
112    public static JsonValue getAuditEventSchema(final JsonValue auditEvent) throws ResourceException {
113        if (auditEvent == null || auditEvent.isNull()) {
114            throw new InternalServerErrorException("Can't get the schema for an undefined audit event");
115        }
116        return auditEvent.get(SCHEMA);
117    }
118
119    /**
120     * Converts JsonPointer field identifier to dotted-path form.
121     *
122     * @param fieldName The JsonPointer reference to a field within a JSON object.
123     * @return The field name in dotted-path form.
124     */
125    public static String jsonPointerToDotNotation(final String fieldName) {
126        String newPath = fieldName;
127        if (fieldName.startsWith("/")) {
128            newPath = fieldName.substring(1);
129        }
130        return (newPath == null) ? null : newPath.replace('/', '.');
131    }
132
133    /**
134     * Converts dotted-path field identifier to JsonPointer form.
135     *
136     * @param fieldName The dotted-path reference to a field within a JSON object.
137     * @return The field name in JsonPointer form.
138     */
139    public static String dotNotationToJsonPointer(final String fieldName) {
140        return (fieldName == null) ? null : fieldName.replace('.', '/');
141    }
142
143}