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.config.parameters.Description;
22 import org.apache.rat.config.parameters.DescriptionBuilder;
23 import org.apache.rat.configuration.builders.AllBuilder;
24 import org.apache.rat.configuration.builders.AnyBuilder;
25 import org.apache.rat.configuration.builders.CopyrightBuilder;
26 import org.apache.rat.configuration.builders.MatcherRefBuilder;
27 import org.apache.rat.configuration.builders.NotBuilder;
28 import org.apache.rat.configuration.builders.RegexBuilder;
29 import org.apache.rat.configuration.builders.SpdxBuilder;
30 import org.apache.rat.configuration.builders.TextBuilder;
31
32 /**
33 * Performs explicit checks against a line from the header of a file. For
34 * implementations that need to check multiple lines the implementation must
35 * cache the earlier lines.
36 */
37 public interface IHeaderMatcher {
38 /**
39 * Get the identifier for this matcher.
40 * <p>
41 * All matchers must have unique identifiers
42 * </p>
43 *
44 * @return the identifier for this matcher.
45 */
46 String getId();
47
48 /**
49 * Resets this state of this matcher to its initial state in preparation for
50 * use with another document scan. In most cases this method does not need to
51 * do anything.
52 */
53 default void reset() {
54 // does nothing.
55 }
56
57 /**
58 * Attempts to match text in the IHeaders instance.
59 *
60 * @param headers the representations of the headers to check
61 * @return {@code true} if the matcher matches the text, {@code false} otherwise.
62 */
63 boolean matches(IHeaders headers);
64
65 /**
66 * Generates the component Description.
67 * @return the component description.
68 */
69 default Description getDescription() {
70 return DescriptionBuilder.build(this);
71 }
72
73 /**
74 * An IHeaderMatcher builder.
75 */
76 @FunctionalInterface
77 interface Builder {
78 /**
79 * Build the IHeaderMatcher.
80 * <p>
81 * Implementations of this interface should return a specific child class of IHeaderMatcher.
82 *
83 * @return a new IHeaderMatcher.
84 */
85 IHeaderMatcher build();
86
87 /**
88 * Gets the description for this builder.
89 * @return The description of the builder
90 */
91 default Description getDescription() {
92 return DescriptionBuilder.buildMap(this.getClass());
93 }
94
95 /**
96 * @return an instance of the standard TextBuilder.
97 * @see TextBuilder
98 * @deprecated Use new TextBuilder()
99 */
100 @Deprecated // since 0.17
101 static TextBuilder text() {
102 return new TextBuilder();
103 }
104
105 /**
106 * @return an instance of the standard AnyBuilder.
107 * @see AnyBuilder
108 * @deprecated Use new AnyBuilder()
109 */
110 @Deprecated // since 0.17
111 static AnyBuilder any() {
112 return new AnyBuilder();
113 }
114
115 /**
116 * @return an instance of the standard AllBuilder.
117 * @see AllBuilder
118 * @deprecated Use new AllBuilder()
119 */
120 @Deprecated // since 0.17
121 static AllBuilder all() {
122 return new AllBuilder();
123 }
124
125 /**
126 * @return an instance of the standard CopyrightBuilder.
127 * @see CopyrightBuilder
128 * @deprecated Use new CopyrightBuilder()
129 */
130 @Deprecated // since 0.17
131 static CopyrightBuilder copyright() {
132 return new CopyrightBuilder();
133 }
134
135 /**
136 * @return an instance of the standard SpdxBuilder.
137 * @see SpdxBuilder
138 * @deprecated Use new SpdxBuilder()
139 */
140 @Deprecated // since 0.17
141 static SpdxBuilder spdx() {
142 return new SpdxBuilder();
143 }
144
145 /**
146 * @return an instance of the standard MatcherRefBuilder.
147 * @see MatcherRefBuilder
148 * @deprecated Use new MatcherRefBuilder()
149 */
150 @Deprecated // since 0.17
151 static MatcherRefBuilder matcherRef() {
152 return new MatcherRefBuilder();
153 }
154
155 /**
156 * @return an instance of the standard NotBuilder.
157 * @see NotBuilder
158 * @deprecated Use new NotBuilder()
159 */
160 @Deprecated // since 0.17
161 static NotBuilder not() {
162 return new NotBuilder();
163 }
164
165 /**
166 * @return an instance of the standard RegexBuilder.
167 * @see RegexBuilder
168 * @deprecated Use new RegexBuilder()
169 */
170 @Deprecated // since 0.17
171 static RegexBuilder regex() {
172 return new RegexBuilder();
173 }
174 }
175 }