1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one *
3 * or more contributor license agreements. See the NOTICE file *
4 * distributed with this work for additional information *
5 * regarding copyright ownership. The ASF licenses this file *
6 * to you under the Apache License, Version 2.0 (the *
7 * "License"); you may not use this file except in compliance *
8 * with the License. You may obtain a copy of the License at *
9 * *
10 * http://www.apache.org/licenses/LICENSE-2.0 *
11 * *
12 * Unless required by applicable law or agreed to in writing, *
13 * software distributed under the License is distributed on an *
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
15 * KIND, either express or implied. See the License for the *
16 * specific language governing permissions and limitations *
17 * under the License. *
18 */
19 package org.apache.rat.analysis;
20
21 import org.apache.rat.ImplementationException;
22 import org.apache.rat.config.parameters.Description;
23 import org.apache.rat.config.parameters.DescriptionBuilder;
24 import org.apache.rat.configuration.builders.AllBuilder;
25 import org.apache.rat.configuration.builders.AnyBuilder;
26 import org.apache.rat.configuration.builders.CopyrightBuilder;
27 import org.apache.rat.configuration.builders.MatcherRefBuilder;
28 import org.apache.rat.configuration.builders.NotBuilder;
29 import org.apache.rat.configuration.builders.RegexBuilder;
30 import org.apache.rat.configuration.builders.SpdxBuilder;
31 import org.apache.rat.configuration.builders.TextBuilder;
32
33 /**
34 * Performs explicit checks against a line from the header of a file. For
35 * implementations that need to check multiple lines the implementation must
36 * cache the earlier lines.
37 */
38 public interface IHeaderMatcher {
39 /**
40 * Get the identifier for this matcher.
41 * <p>
42 * All matchers must have unique identifiers
43 * </p>
44 *
45 * @return the Identifier for this matcher.
46 */
47 String getId();
48
49 /**
50 * Resets this state of this matcher to its initial state in preparation for
51 * use with another document scan. In most cases this method does not need to
52 * do anything.
53 */
54 default void reset() {
55 // does nothing.
56 }
57
58 /**
59 * Attempts to match text in the IHeaders instance.
60 *
61 * @param headers the representations of the headers to check
62 * @return {@code true} if the matcher matches the text, {@code false} otherwise.
63 */
64 boolean matches(IHeaders headers);
65
66 /**
67 * Generates the component Description.
68 * @return the component description.
69 */
70 default Description getDescription() {
71 return DescriptionBuilder.build(this);
72 }
73
74 /**
75 * An IHeaderMatcher builder.
76 */
77 @FunctionalInterface
78 interface Builder {
79 /**
80 * Build the IHeaderMatcher.
81 *
82 * Implementations of this interface should return a specific child class of IHeaderMatcher.
83 *
84 * @return a new IHeaderMatcher.
85 */
86 IHeaderMatcher build();
87
88 /**
89 * Gets the class that is build by this builder.
90 * @return The class that is build by this builder.
91 */
92 default Class<?> builtClass() throws SecurityException {
93 try {
94 return this.getClass().getMethod("build").getReturnType();
95 } catch (NoSuchMethodException | SecurityException e) {
96 throw new IllegalStateException("the 'build' method of the Builder interface must always be public");
97 }
98 }
99
100 /**
101 * Gets the Description for this builder.
102 * @return The description of the builder
103 */
104 default Description getDescription() {
105 Class<?> clazz = builtClass();
106 if (clazz == IHeaderMatcher.class) {
107 throw new ImplementationException(String.format(
108 "Class %s must implement buildClass() method to return a child class of IHeaderMatcher",
109 this.getClass()));
110 }
111 return DescriptionBuilder.buildMap(clazz);
112 }
113
114 /**
115 * @return an instance of the standard TextBuilder.
116 * @see TextBuilder
117 */
118 static TextBuilder text() {
119 return new TextBuilder();
120 }
121
122 /**
123 * @return an instance of the standard AnyBuilder.
124 * @see AnyBuilder
125 */
126 static AnyBuilder any() {
127 return new AnyBuilder();
128 }
129
130 /**
131 * @return an instance of the standard AllBuilder.
132 * @see AllBuilder
133 */
134 static AllBuilder all() {
135 return new AllBuilder();
136 }
137
138 /**
139 * @return an instance of the standard CopyrightBuilder.
140 * @see CopyrightBuilder
141 */
142 static CopyrightBuilder copyright() {
143 return new CopyrightBuilder();
144 }
145
146 /**
147 * @return an instance of the standard SpdxBuilder.
148 * @see SpdxBuilder
149 */
150 static SpdxBuilder spdx() {
151 return new SpdxBuilder();
152 }
153
154 /**
155 * @return an instance of the standard MatcherRefBuilder.
156 * @see MatcherRefBuilder
157 */
158 static MatcherRefBuilder matcherRef() {
159 return new MatcherRefBuilder();
160 }
161
162 /**
163 * @return an instance of the standard NotBuilder.
164 * @see NotBuilder
165 */
166 static NotBuilder not() {
167 return new NotBuilder();
168 }
169
170 /**
171 * @return an instance of the standard RegexBuilder.
172 * @see RegexBuilder
173 */
174 static RegexBuilder regex() {
175 return new RegexBuilder();
176 }
177 }
178 }