1 /**
2 * Copyright (C) 2014-2017 Philip Helger (www.helger.com)
3 * philip[at]helger[dot]com
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package com.helger.schematron.pure.binding;
18
19 import java.io.Serializable;
20 import java.util.List;
21 import java.util.Map;
22
23 import javax.annotation.Nonnull;
24 import javax.annotation.Nullable;
25 import javax.xml.xpath.XPathFunctionResolver;
26 import javax.xml.xpath.XPathVariableResolver;
27
28 import com.helger.commons.annotation.ReturnsMutableCopy;
29 import com.helger.commons.collection.ext.ICommonsNavigableMap;
30 import com.helger.schematron.SchematronException;
31 import com.helger.schematron.pure.bound.IPSBoundSchema;
32 import com.helger.schematron.pure.errorhandler.IPSErrorHandler;
33 import com.helger.schematron.pure.model.PSAssertReport;
34 import com.helger.schematron.pure.model.PSParam;
35 import com.helger.schematron.pure.model.PSRule;
36 import com.helger.schematron.pure.model.PSSchema;
37 import com.helger.schematron.pure.model.PSValueOf;
38
39 /**
40 * Base interface for a single query binding.
41 *
42 * @author Philip Helger
43 */
44 public interface IPSQueryBinding extends Serializable
45 {
46 // --- requirements to create a minimal syntax/pre-process ---
47
48 /**
49 * Negate the passed test statement. This is required in the creation of a
50 * minified Schematron, when report elements are converted to assert elements.
51 *
52 * @param sTest
53 * The test expression.
54 * @return The negated test expression
55 */
56 String getNegatedTestExpression (@Nonnull String sTest);
57
58 /**
59 * Convert the passed list of {@link PSParam} elements to a map suitable for
60 * String replacement. This is needed to resolve placeholders in abstract
61 * patterns. The default query binding e.g. adds a "$" in front of each
62 * parameter name. The so created map is used to resolve abstract rule and
63 * pattern data to real values.
64 *
65 * @param aParams
66 * Source list. May not be <code>null</code>.
67 * @return Non-<code>null</code> String replacement map.
68 */
69 @Nonnull
70 @ReturnsMutableCopy
71 ICommonsNavigableMap <String, String> getStringReplacementMap (@Nonnull List <PSParam> aParams);
72
73 /**
74 * Apply the Map created by {@link #getNegatedTestExpression(String)} on a
75 * single string.<br>
76 * According to iso_abstract_expand.xsl, line 233 the text replacements happen
77 * for the following attributes:
78 * <ul>
79 * <li>test - only in {@link PSAssertReport}</li>
80 * <li>context - only in {@link PSRule}</li>
81 * <li>select - only in {@link PSValueOf}</li>
82 * </ul>
83 * As an experimental option in line 244 the replacement is also applied to
84 * all text nodes. This is currently not supported!
85 *
86 * @param sText
87 * The original text. May be <code>null</code>.
88 * @param aStringReplacements
89 * All replacements as map from source to target. The map should be
90 * ordered by longest keys first.
91 * @return <code>null</code> if the input string was <code>null</code>.
92 */
93 @Nullable
94 String getWithParamTextsReplaced (@Nullable String sText, @Nullable Map <String, String> aStringReplacements);
95
96 // --- requirements for compilation ---
97
98 /**
99 * Create a bound schema, which is like a precompiled schema.
100 *
101 * @param aSchema
102 * The schema to be bound. May not be <code>null</code>.
103 * @param sPhase
104 * The phase to use. May be <code>null</code>. If it is
105 * <code>null</code> than the defaultPhase is used that is defined in
106 * the schema. If no defaultPhase is present, than all patterns are
107 * evaluated.
108 * @param aCustomErrorHandler
109 * An optional custom error handler to use. May be <code>null</code>.
110 * @param aVariableResolver
111 * Custom variable resolver. May be <code>null</code>.
112 * @param aFunctionResolver
113 * Custom function resolver. May be <code>null</code>.
114 * @return The precompiled, bound schema. Never <code>null</code>.
115 * @throws SchematronException
116 * In case of a binding error
117 */
118 @Nonnull
119 IPSBoundSchema bind (@Nonnull PSSchema aSchema,
120 @Nullable String sPhase,
121 @Nullable IPSErrorHandler aCustomErrorHandler,
122 @Nullable XPathVariableResolver aVariableResolver,
123 @Nullable XPathFunctionResolver aFunctionResolver) throws SchematronException;
124 }