1 /**
2 * Copyright (C) 2014-2015 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.schematron.SchematronException;
30 import com.helger.schematron.pure.bound.IPSBoundSchema;
31 import com.helger.schematron.pure.errorhandler.IPSErrorHandler;
32 import com.helger.schematron.pure.model.PSAssertReport;
33 import com.helger.schematron.pure.model.PSParam;
34 import com.helger.schematron.pure.model.PSRule;
35 import com.helger.schematron.pure.model.PSSchema;
36 import com.helger.schematron.pure.model.PSValueOf;
37
38 /**
39 * Base interface for a single query binding.
40 *
41 * @author Philip Helger
42 */
43 public interface IPSQueryBinding extends Serializable
44 {
45 // --- requirements to create a minimal syntax/pre-process ---
46
47 /**
48 * Negate the passed test statement. This is required in the creation of a
49 * minified Schematron, when report elements are converted to assert elements.
50 *
51 * @param sTest
52 * The test expression.
53 * @return The negated test expression
54 */
55 String getNegatedTestExpression (@Nonnull String sTest);
56
57 /**
58 * Convert the passed list of {@link PSParam} elements to a map suitable for
59 * String replacement. This is needed to resolve placeholders in abstract
60 * patterns. The default query binding e.g. adds a "$" in front of each
61 * parameter name. The so created map is used to resolve abstract rule and
62 * pattern data to real values.
63 *
64 * @param aParams
65 * Source list. May not be <code>null</code>.
66 * @return Non-<code>null</code> String replacement map.
67 */
68 @Nonnull
69 @ReturnsMutableCopy
70 Map <String, String> getStringReplacementMap (@Nonnull List <PSParam> aParams);
71
72 /**
73 * Apply the Map created by {@link #getNegatedTestExpression(String)} on a
74 * single string.<br>
75 * According to iso_abstract_expand.xsl, line 233 the text replacements happen
76 * for the following attributes:
77 * <ul>
78 * <li>test - only in {@link PSAssertReport}</li>
79 * <li>context - only in {@link PSRule}</li>
80 * <li>select - only in {@link PSValueOf}</li>
81 * </ul>
82 * As an experimental option in line 244 the replacement is also applied to
83 * all text nodes. This is currently not supported!
84 *
85 * @param sText
86 * The original text. May be <code>null</code>.
87 * @param aStringReplacements
88 * All replacements as map from source to target. The map should be
89 * ordered by longest keys first.
90 * @return <code>null</code> if the input string was <code>null</code>.
91 */
92 @Nullable
93 String getWithParamTextsReplaced (@Nullable String sText, @Nullable Map <String, String> aStringReplacements);
94
95 // --- requirements for compilation ---
96
97 /**
98 * Create a bound schema, which is like a precompiled schema.
99 *
100 * @param aSchema
101 * The schema to be bound. May not be <code>null</code>.
102 * @param sPhase
103 * The phase to use. May be <code>null</code>. If it is
104 * <code>null</code> than the defaultPhase is used that is defined in
105 * the schema. If no defaultPhase is present, than all patterns are
106 * evaluated.
107 * @param aCustomErrorHandler
108 * An optional custom error handler to use. May be <code>null</code>.
109 * @param aVariableResolver
110 * Custom variable resolver. May be <code>null</code>.
111 * @param aFunctionResolver
112 * Custom function resolver. May be <code>null</code>.
113 * @return The precompiled, bound schema. Never <code>null</code>.
114 * @throws SchematronException
115 * In case of a binding error
116 */
117 @Nonnull
118 IPSBoundSchema bind (@Nonnull PSSchema aSchema,
119 @Nullable String sPhase,
120 @Nullable IPSErrorHandler aCustomErrorHandler,
121 @Nullable XPathVariableResolver aVariableResolver,
122 @Nullable XPathFunctionResolver aFunctionResolver) throws SchematronException;
123 }