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.audit.json;
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.io.IOException;
023import java.io.InputStream;
024import java.util.LinkedHashMap;
025import java.util.Map;
026
027import org.forgerock.audit.AuditException;
028import org.forgerock.audit.AuditServiceBuilder;
029import org.forgerock.audit.AuditServiceConfiguration;
030import org.forgerock.audit.events.handlers.AuditEventHandler;
031import org.forgerock.audit.events.handlers.EventHandlerConfiguration;
032import org.forgerock.audit.util.JsonValueUtils;
033import org.forgerock.json.JsonValue;
034import org.slf4j.Logger;
035import org.slf4j.LoggerFactory;
036
037import com.fasterxml.jackson.annotation.JsonPropertyDescription;
038import com.fasterxml.jackson.databind.AnnotationIntrospector;
039import com.fasterxml.jackson.databind.ObjectMapper;
040import com.fasterxml.jackson.databind.introspect.Annotated;
041import com.fasterxml.jackson.databind.introspect.JacksonAnnotationIntrospector;
042import com.fasterxml.jackson.module.jsonSchema.JsonSchema;
043import com.fasterxml.jackson.module.jsonSchema.factories.SchemaFactoryWrapper;
044
045/**
046 * Utility class to facilitate creation and configuration of audit service and audit event handlers
047 * through JSON.
048 */
049public class AuditJsonConfig {
050    private static final Logger logger = LoggerFactory.getLogger(AuditJsonConfig.class);
051
052    /** Field containing the name of an event handler. */
053    private static final String NAME_FIELD = "name";
054    /** Field containing the implementation class of an event handler. */
055    private static final String CLASS_FIELD = "class";
056    /** Field containing the configuration of an event handler. */
057    private static final String CONFIG_FIELD = "config";
058    /** Field containing events topics to process for an event handler. */
059    private static final String EVENTS_FIELD = "events";
060
061    /** The mapper from JSON structure to Java object. */
062    //checkstyle:off
063    private static final ObjectMapper mapper = new ObjectMapper();
064    // checkstyle:on
065
066    private static final AnnotationIntrospector defaultAnnotationIntrospector = new JacksonAnnotationIntrospector();
067    private static final AnnotationIntrospector helpAppenderAnnotationIntrospector =
068            new HelpAppenderAnnotationIntrospector();
069
070    private AuditJsonConfig() {
071        // prevent instantiation of the class
072    }
073
074    /**
075     * Returns a JSON value from the provided input stream.
076     *
077     * @param input
078     *          Input stream containing an arbitrary JSON structure.
079     * @return the JSON value corresponding to the JSON structure
080     * @throws AuditException
081     *          If an error occurs.
082     */
083    public static JsonValue getJson(InputStream input) throws AuditException {
084        try {
085            return new JsonValue(mapper.readValue(input, LinkedHashMap.class));
086        } catch (IOException e) {
087            throw new AuditException(String.format("Unable to retrieve json value from json input stream"), e);
088        }
089    }
090
091    /**
092     * Returns the audit service configuration from the provided input stream.
093     *
094     * @param input
095     *          Input stream containing JSON configuration of the audit service.
096     * @return the configuration object
097     * @throws AuditException
098     *          If any error occurs.
099     */
100    public static AuditServiceConfiguration parseAuditServiceConfiguration(InputStream input) throws AuditException {
101        try {
102            return mapper.readValue(input, AuditServiceConfiguration.class);
103        } catch (IOException e) {
104            throw new AuditException(String.format("Unable to retrieve class %s from json input stream",
105                    AuditServiceConfiguration.class), e);
106        }
107    }
108
109    /**
110     * Returns the audit service configuration from the provided JSON string.
111     *
112     * @param json
113     *          JSON string representing the configuration of the audit service.
114     * @return the configuration object
115     * @throws AuditException
116     *          If any error occurs.
117     */
118    public static AuditServiceConfiguration parseAuditServiceConfiguration(String json) throws AuditException {
119        if (json == null) {
120            return new AuditServiceConfiguration();
121        }
122        try {
123            return mapper.readValue(json, AuditServiceConfiguration.class);
124        } catch (IOException e) {
125            throw new AuditException(String.format("Unable to retrieve class %s from json: %s",
126                    AuditServiceConfiguration.class, json), e);
127        }
128    }
129
130    /**
131     * Returns the audit service configuration from the provided JSON value.
132     *
133     * @param json
134     *          JSON value representing the configuration of the audit service.
135     * @return the configuration object
136     * @throws AuditException
137     *          If any error occurs.
138     */
139    public static AuditServiceConfiguration parseAuditServiceConfiguration(JsonValue json) throws AuditException {
140        return parseAuditServiceConfiguration(JsonValueUtils.extractValueAsString(json, "/"));
141    }
142
143    /**
144     * Configures and registers the audit event handler corresponding to the provided JSON configuration
145     * to the provided audit service.
146     *
147     * @param jsonConfig
148     *          The configuration of the audit event handler as JSON.
149     * @param auditServiceBuilder
150     *          The builder for the service the event handler will be registered to.
151     * @throws AuditException
152     *             If any error occurs during configuration or registration of the handler.
153     */
154    public static void registerHandlerToService(JsonValue jsonConfig, AuditServiceBuilder auditServiceBuilder)
155            throws AuditException {
156        registerHandlerToService(jsonConfig, auditServiceBuilder, auditServiceBuilder.getClass().getClassLoader());
157    }
158
159    /**
160     * Configures and registers the audit event handler corresponding to the provided JSON configuration
161     * to the provided audit service, using a specific class loader.
162     *
163     * @param jsonConfig
164     *          The configuration of the audit event handler as JSON.
165     * @param auditServiceBuilder
166     *          The builder for the service the event handler will be registered to.
167     * @param classLoader
168     *          The class loader to use to load the handler and its configuration class.
169     * @throws AuditException
170     *             If any error occurs during configuration or registration of the handler.
171     */
172    public static void registerHandlerToService(JsonValue jsonConfig,
173            AuditServiceBuilder auditServiceBuilder, ClassLoader classLoader) throws AuditException {
174        String name = getHandlerName(jsonConfig);
175        Class<? extends AuditEventHandler> handlerClass = getAuditEventHandlerClass(name, jsonConfig, classLoader);
176        Class<? extends EventHandlerConfiguration> configClass =
177                getAuditEventHandlerConfigurationClass(name, handlerClass, classLoader);
178        EventHandlerConfiguration configuration = parseAuditEventHandlerConfiguration(configClass, jsonConfig);
179        auditServiceBuilder.withAuditEventHandler(handlerClass, configuration);
180    }
181
182    /**
183     * Returns the name of the event handler corresponding to provided JSON configuration.
184     * <p>
185     * The JSON configuration is expected to contains a "name" field identifying the
186     * event handler, e.g.
187     * <pre>
188     *  "name" : "passthrough"
189     * </pre>
190     *
191     * @param jsonConfig
192     *          The JSON configuration of the event handler.
193     * @return the name of the event handler
194     * @throws AuditException
195     *          If an error occurs.
196     */
197    private static String getHandlerName(JsonValue jsonConfig) throws AuditException {
198        String name = jsonConfig.get(CONFIG_FIELD).get(NAME_FIELD).asString();
199        if (name == null) {
200            throw new AuditException(String.format("No name is defined for the provided audit handler. "
201                    + "You must define a 'name' property in the configuration."));
202        }
203        return name;
204    }
205
206    /**
207     * Creates an audit event handler factory from the provided JSON configuration.
208     * <p>
209     * The JSON configuration is expected to contains a "class" property which provides
210     * the class name for the handler factory to instantiate.
211     *
212     * @param jsonConfig
213     *          The configuration of the audit event handler as JSON.
214     * @param classLoader
215     *          The class loader to use to load the handler and its configuration class.
216     * @return the fully configured audit event handler
217     * @throws AuditException
218     *             If any error occurs during configuration or registration of the handler.
219     */
220    @SuppressWarnings("unchecked") // Class.forName calls
221    private static Class<? extends AuditEventHandler> getAuditEventHandlerClass(
222            String handlerName, JsonValue jsonConfig, ClassLoader classLoader) throws AuditException {
223        // TODO: class name should not be provided in customer configuration
224        // but through a commons module/service context
225        String className = jsonConfig.get(CLASS_FIELD).asString();
226        if (className == null) {
227            String errorMessage = String.format("No class is defined for the audit handler %s. "
228                    + "You must define a 'class' property in the configuration.", handlerName);
229            throw new AuditException(errorMessage);
230        }
231        try {
232            return (Class<? extends AuditEventHandler>) Class.forName(className, true, classLoader);
233        } catch (ClassNotFoundException e) {
234            String errorMessage = String.format("Invalid class is defined for the audit handler %s.", handlerName);
235            throw new AuditException(errorMessage, e);
236        }
237    }
238
239    @SuppressWarnings("unchecked") // Class.forName calls
240    private static Class<? extends EventHandlerConfiguration> getAuditEventHandlerConfigurationClass(
241            String handlerName, Class<? extends AuditEventHandler> handlerClass, ClassLoader classLoader)
242            throws AuditException {
243        String className = handlerClass.getName() + "Configuration";
244        try {
245            return (Class<? extends EventHandlerConfiguration>) Class.forName(className, true, classLoader);
246        } catch (ClassNotFoundException e) {
247            String errorMessage = String.format("Unable to locate configuration class %s for the audit handler %s.",
248                    className, handlerName);
249            throw new AuditException(errorMessage, e);
250        }
251    }
252
253    /**
254     * Returns the audit event handler configuration from the provided JSON string.
255     *
256     * @param <C>
257     *          The type of the configuration bean for the event handler.
258     * @param jsonConfig
259     *          The configuration of the audit event handler as JSON.
260     * @return the fully configured audit event handler
261     * @throws AuditException
262     *             If any error occurs while instantiating the configuration from JSON.
263     */
264    private static <C extends EventHandlerConfiguration> C parseAuditEventHandlerConfiguration(
265            Class<C> clazz, JsonValue jsonConfig) throws AuditException {
266        C configuration = null;
267        JsonValue conf = jsonConfig.get(CONFIG_FIELD);
268        if (conf != null) {
269            configuration = mapper.convertValue(conf.getObject(), clazz);
270        }
271        return configuration;
272    }
273
274    /**
275     * Gets the configuration schema for an audit event handler as json schema. The supplied json config must contain
276     * a field called class with the value of the audit event handler implementation class.
277     * @param className The class name to get the configuration for.
278     * @param classLoader The {@link ClassLoader} to use to load the event handler and event handler config class.
279     * @return The config schema as json schema.
280     * @throws AuditException If any error occurs parsing the config class for schema.
281     */
282    public static JsonValue getAuditEventHandlerConfigurationSchema(final String className,
283            final ClassLoader classLoader) throws AuditException {
284        final Class<? extends EventHandlerConfiguration> eventHandlerConfiguration =
285                getAuditEventHandlerConfigurationClass(
286                        className,
287                        getAuditEventHandlerClass(
288                                className,
289                                json(object(field("class", className))),
290                                classLoader),
291                        classLoader);
292        try {
293            mapper.setAnnotationIntrospector(helpAppenderAnnotationIntrospector);
294            SchemaFactoryWrapper visitor = new SchemaFactoryWrapper();
295            mapper.acceptJsonFormatVisitor(mapper.constructType(eventHandlerConfiguration), visitor);
296            JsonSchema jsonSchema = visitor.finalSchema();
297            final JsonValue schema = json(mapper.readValue(mapper.writeValueAsString(jsonSchema), Map.class));
298            mapper.setAnnotationIntrospector(defaultAnnotationIntrospector);
299            return schema;
300        } catch (IOException e) {
301            final String error = String.format("Unable to parse configuration class schema for configuration class %s",
302                    eventHandlerConfiguration.getName());
303            logger.error(error, e);
304            throw new AuditException(error, e);
305        }
306    }
307
308    /**
309     * Extends the default {@link JacksonAnnotationIntrospector} and overrides the {@link JsonPropertyDescription}
310     * annotation inorder to append ".help" to the description.
311     */
312    private static class HelpAppenderAnnotationIntrospector extends JacksonAnnotationIntrospector {
313        @Override
314        public String findPropertyDescription(Annotated ann) {
315            JsonPropertyDescription desc = _findAnnotation(ann, JsonPropertyDescription.class);
316            return (desc == null) ? null : desc.value().concat(".help");
317        }
318    }
319
320}