001/*
002 * (C) Copyright 2014 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Nicolas Chapurlat <[email protected]>
018 */
019
020package org.nuxeo.ecm.core.api.validation;
021
022import java.io.Serializable;
023import java.util.Map;
024
025import org.nuxeo.ecm.core.api.DocumentModel;
026import org.nuxeo.ecm.core.api.model.Property;
027import org.nuxeo.ecm.core.schema.types.Field;
028import org.nuxeo.ecm.core.schema.types.Schema;
029
030/**
031 * Provides a way to validate {@link DocumentModel} according to their {@link Schema}'s constraints.
032 *
033 * @since 7.1
034 */
035public interface DocumentValidationService {
036
037    public static final String CTX_MAP_KEY = "DocumentValidationService.Forcing";
038
039    public static final String CTX_CREATEDOC = "createDocument";
040
041    public static final String CTX_SAVEDOC = "saveDocument";
042
043    public static final String CTX_IMPORTDOC = "importDocument";
044
045    public static enum Forcing {
046        TURN_ON, TURN_OFF, USUAL;
047    }
048
049    /**
050     * To activate validation in some context, for example "CoreSession.saveDocument", you have to contribute to
051     * component "org.nuxeo.ecm.core.api.DocumentValidationService" with extension point "activations".
052     * <p>
053     * Example :
054     * </p>
055     *
056     * <pre>
057     * {@code
058     * <extension target="org.nuxeo.ecm.core.api.DocumentValidationService" point="activations">
059     *   <validation context="CoreSession.saveDocument" activated="false" />
060     * </extension>
061     * }
062     * </pre>
063     * <p>
064     * Here are some available context :
065     * </p>
066     * <ul>
067     * <li>CoreSession.createDocument</li>
068     * <li>CoreSession.saveDocument</li>
069     * <li>CoreSession.importDocument</li>
070     * </ul>
071     *
072     * @param context A string representation of the context, where validation service should be activated.
073     * @param contextMap if not null, search forcing flag in the context map. see {@link Forcing} for values and
074     *            {@link #CTX_MAP_KEY} for the key.
075     * @return true if validation is activated in the specified context, false otherwise.
076     * @since 7.1
077     */
078    boolean isActivated(String context, Map<String, Serializable> contextMap);
079
080    /**
081     * Validates all {@link Field} of all {@link Schema} of a {@link DocumentModel}. Including no dirty properties.
082     *
083     * @since 7.1
084     */
085    DocumentValidationReport validate(DocumentModel document);
086
087    /**
088     * Validates all {@link Field} of all {@link Schema} of a {@link DocumentModel}.
089     *
090     * @param dirtyOnly If true, limit validation to dirty properties of the {@link DocumentModel}.
091     * @since 7.1
092     */
093    DocumentValidationReport validate(DocumentModel document, boolean dirtyOnly);
094
095    /**
096     * Validates a value according to some {@link Field} definition.
097     *
098     * @since 7.1
099     */
100    DocumentValidationReport validate(Field field, Object value);
101
102    /**
103     * Validates a value according to some {@link Field} definition.
104     *
105     * @param validateSubProperties Tell whether the sub properties must be validated.
106     * @since 7.2
107     */
108    DocumentValidationReport validate(Field field, Object value, boolean validateSubProperties);
109
110    /**
111     * Validates a property according to its {@link Field} definition.
112     *
113     * @since 7.1
114     */
115    DocumentValidationReport validate(Property property);
116
117    /**
118     * Validates a property according to its {@link Field} definition.
119     *
120     * @param validateSubProperties Tell whether the sub properties must be validated.
121     * @since 7.10
122     */
123    DocumentValidationReport validate(Property property, boolean validateSubProperties);
124
125    /**
126     * Validates a value according to some {@link Field} definition.
127     *
128     * @param xpath schema:fieldName, for example dc:title - the xpath could also be a value that match a complex
129     *            property field (for example, an field of a complex type in a list: schema:list:complex:field).
130     * @throws IllegalArgumentException If the xpath does not match any field.
131     * @since 7.1
132     */
133    DocumentValidationReport validate(String xpath, Object value);
134
135    /**
136     * Validates a value according to some {@link Field} definition.
137     *
138     * @param xpath schema:fieldName, for example dc:title - the xpath could also be a value that match a complex
139     *            property field (for example, an field of a complex type in a list: schema:list:complex:field).
140     * @param validateSubProperties Tell whether the sub properties must be validated.
141     * @throws IllegalArgumentException If the xpath does not match any field.
142     * @since 7.10
143     */
144    DocumentValidationReport validate(String xpath, Object value, boolean validateSubProperties);
145
146}