} = {};
126 |
127 | if (resourceType.oldType !== undefined && resourceType.oldType === resourceType.newType) {
128 | // Only makes sense to inspect deeper if the types stayed the same
129 | const typeSpec = cfnspec.filteredSpecification(resourceType.oldType);
130 | const impl = typeSpec.ResourceTypes[resourceType.oldType];
131 | propertyDiffs = diffKeyedEntities(oldValue!.Properties,
132 | newValue!.Properties,
133 | (oldVal, newVal, key) => _diffProperty(oldVal, newVal, key, impl));
134 |
135 | otherDiffs = diffKeyedEntities(oldValue, newValue, _diffOther);
136 | delete otherDiffs.Properties;
137 | }
138 |
139 | return new types.ResourceDifference(oldValue, newValue, {
140 | resourceType, propertyDiffs, otherDiffs,
141 | });
142 |
143 | function _diffProperty(oldV: any, newV: any, key: string, resourceSpec?: cfnspec.schema.ResourceType) {
144 | let changeImpact = types.ResourceImpact.NO_CHANGE;
145 |
146 | const spec = resourceSpec && resourceSpec.Properties && resourceSpec.Properties[key];
147 | if (spec && !deepEqual(oldV, newV)) {
148 | switch (spec.UpdateType) {
149 | case cfnspec.schema.UpdateType.Immutable:
150 | changeImpact = types.ResourceImpact.WILL_REPLACE;
151 | break;
152 | case cfnspec.schema.UpdateType.Conditional:
153 | changeImpact = types.ResourceImpact.MAY_REPLACE;
154 | break;
155 | default:
156 | // In those cases, whatever is the current value is what we should keep
157 | changeImpact = types.ResourceImpact.WILL_UPDATE;
158 | }
159 | }
160 |
161 | return new types.PropertyDifference(oldV, newV, { changeImpact });
162 | }
163 |
164 | function _diffOther(oldV: any, newV: any) {
165 | return new types.Difference(oldV, newV);
166 | }
167 | }
168 | ```
169 |
170 | [Rendering diffs in a human-readable form (not listed).](https://github.com/aws/aws-cdk/blob/d88b45eb21bcd051146477e3c97de7dd7b8634d3/packages/%40aws-cdk/cloudformation-diff/lib/format.ts)
171 |
172 | ## Testing
173 |
174 |
175 | [The test suite](https://github.com/aws/aws-cdk/blob/d88b45eb21bcd051146477e3c97de7dd7b8634d3/packages/%40aws-cdk/cloudformation-diff/test/diff-template.test.ts) is quite comprehensive.
176 |
177 | [Basic test for adding a resource](https://github.com/aws/aws-cdk/blob/d88b45eb21bcd051146477e3c97de7dd7b8634d3/packages/%40aws-cdk/cloudformation-diff/test/diff-template.test.ts#L32-L45):
178 | ```typescript
179 | test('when a resource is created', () => {
180 | const currentTemplate = { Resources: {} };
181 |
182 | const newTemplate = { Resources: { BucketResource: { Type: 'AWS::S3::Bucket' } } };
183 |
184 | const differences = diffTemplate(currentTemplate, newTemplate);
185 | expect(differences.differenceCount).toBe(1);
186 | expect(differences.resources.differenceCount).toBe(1);
187 | const difference = differences.resources.changes.BucketResource;
188 | expect(difference).not.toBeUndefined();
189 | expect(difference?.isAddition).toBeTruthy();
190 | expect(difference?.newResourceType).toEqual('AWS::S3::Bucket');
191 | expect(difference?.changeImpact).toBe(ResourceImpact.WILL_CREATE);
192 | });
193 | ```
194 |
195 | [Test cascading changes](https://github.com/aws/aws-cdk/blob/d88b45eb21bcd051146477e3c97de7dd7b8634d3/packages/%40aws-cdk/cloudformation-diff/test/diff-template.test.ts#L279-L323):
196 | ```typescript
197 | test('resource replacement is tracked through references', () => {
198 | // If a resource is replaced, then that change shows that references are
199 | // going to change. This may lead to replacement of downstream resources
200 | // if the reference is used in an immutable property, and so on.
201 |
202 | // GIVEN
203 | const currentTemplate = {
204 | Resources: {
205 | Bucket: {
206 | Type: 'AWS::S3::Bucket',
207 | Properties: { BucketName: 'Name1' }, // Immutable prop
208 | },
209 | Queue: {
210 | Type: 'AWS::SQS::Queue',
211 | Properties: { QueueName: { Ref: 'Bucket' } }, // Immutable prop
212 | },
213 | Topic: {
214 | Type: 'AWS::SNS::Topic',
215 | Properties: { TopicName: { Ref: 'Queue' } }, // Immutable prop
216 | },
217 | },
218 | };
219 |
220 | // WHEN
221 | const newTemplate = {
222 | Resources: {
223 | Bucket: {
224 | Type: 'AWS::S3::Bucket',
225 | Properties: { BucketName: 'Name2' },
226 | },
227 | Queue: {
228 | Type: 'AWS::SQS::Queue',
229 | Properties: { QueueName: { Ref: 'Bucket' } },
230 | },
231 | Topic: {
232 | Type: 'AWS::SNS::Topic',
233 | Properties: { TopicName: { Ref: 'Queue' } },
234 | },
235 | },
236 | };
237 | const differences = diffTemplate(currentTemplate, newTemplate);
238 |
239 | // THEN
240 | expect(differences.resources.differenceCount).toBe(3);
241 | });
242 | ```
243 |
244 | [Testing](https://github.com/aws/aws-cdk/blob/d88b45eb21bcd051146477e3c97de7dd7b8634d3/packages/%40aws-cdk/cloudformation-diff/test/diff-template.test.ts#L434-L460) that it understands that the order of elements in an array matters in some places and doesn't matter in others:
245 |
246 | ```typescript
247 | test('array equivalence is independent of element order in DependsOn expressions', () => {
248 | // GIVEN
249 | const currentTemplate = {
250 | Resources: {
251 | BucketResource: {
252 | Type: 'AWS::S3::Bucket',
253 | DependsOn: ['SomeResource', 'AnotherResource'],
254 | },
255 | },
256 | };
257 |
258 | // WHEN
259 | const newTemplate = {
260 | Resources: {
261 | BucketResource: {
262 | Type: 'AWS::S3::Bucket',
263 | DependsOn: ['AnotherResource', 'SomeResource'],
264 | },
265 | },
266 | };
267 |
268 | let differences = diffTemplate(currentTemplate, newTemplate);
269 | expect(differences.resources.differenceCount).toBe(0);
270 |
271 | differences = diffTemplate(newTemplate, currentTemplate);
272 | expect(differences.resources.differenceCount).toBe(0);
273 | });
274 |
275 | test('arrays of different length are considered unequal in DependsOn expressions', () => {
276 | // GIVEN
277 | const currentTemplate = {
278 | Resources: {
279 | BucketResource: {
280 | Type: 'AWS::S3::Bucket',
281 | DependsOn: ['SomeResource', 'AnotherResource', 'LastResource'],
282 | },
283 | },
284 | };
285 |
286 | // WHEN
287 | const newTemplate = {
288 | Resources: {
289 | BucketResource: {
290 | Type: 'AWS::S3::Bucket',
291 | DependsOn: ['AnotherResource', 'SomeResource'],
292 | },
293 | },
294 | };
295 |
296 | let differences = diffTemplate(currentTemplate, newTemplate);
297 | expect(differences.resources.differenceCount).toBe(1);
298 |
299 | differences = diffTemplate(newTemplate, currentTemplate);
300 | expect(differences.resources.differenceCount).toBe(1);
301 | });
302 | ```
303 |
304 | ## Observations
305 |
306 | * Some resources ([IAM](https://github.com/aws/aws-cdk/tree/d88b45eb21bcd051146477e3c97de7dd7b8634d3/packages/%40aws-cdk/cloudformation-diff/lib/iam), [networking](https://github.com/aws/aws-cdk/tree/d88b45eb21bcd051146477e3c97de7dd7b8634d3/packages/%40aws-cdk/cloudformation-diff/lib/network)) require special treatment.
307 |
308 | ## Related
309 |
310 | [Terraform](https://github.com/hashicorp/terraform/), a competing product, [implements a similar algorithm](https://github.com/hashicorp/terraform/blob/d35bc0531255b496beb5d932f185cbcdb2d61a99/internal/legacy/terraform/diff.go).
311 |
312 | ## References
313 |
314 | * [GitHub Repo](https://github.com/aws/aws-cdk)
315 | * [Product website](https://aws.amazon.com/cdk/)
316 | * [Documentation](https://docs.aws.amazon.com/cdk/index.html)
317 | * [Sample templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/sample-templates-services-us-west-2.html)
318 |
319 | ## Copyright notice
320 |
321 | AWS CDK is licensed under the [Apache License 2.0](https://github.com/aws/aws-cdk/blob/master/LICENSE).
322 |
323 | Copyright 2018-2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
324 |
--------------------------------------------------------------------------------
/_articles/error-prone-test-helper.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Error Prone - Testing Bug Checkers [Java]"
3 | layout: default
4 | last_modified_date: 2021-09-01T17:57:00+0300
5 | nav_order: 2
6 |
7 | status: PUBLISHED
8 | language: Java
9 | short-title: Testing Bug Checkers
10 | project:
11 | name: Error Prone
12 | key: error-prone
13 | home-page: https://github.com/google/error-prone
14 | tags: [dsl, test-helper, builder]
15 | ---
16 |
17 | {% include article-meta.html article=page %}
18 |
19 | ## Context
20 |
21 | [Error Prone](https://errorprone.info) is a static analysis tool for Java that catches common programming mistakes at compile-time.
22 |
23 | Error Prone is comprised of hundreds of different checkers searching for different types of defects. Checkers inherit the same base class [`BugChecker`](https://github.com/google/error-prone/blob/c601758e81723a8efc4671726b8363be7a306dce/check_api/src/main/java/com/google/errorprone/bugpatterns/BugChecker.java#). In the nutshell, the interface for a checker is *unit of code (class, method, etc.) in - findings out*.
24 |
25 | ## Problem
26 |
27 | There must be an easy and uniform way to test checkers. Tests must be easy to read and easy to write. They must be agnostic to how source code is represented and how these representations (abstract syntax trees, etc.) are built, how the checker interacts with the rest of the system, etc.
28 |
29 | ## Overview
30 |
31 | Error Prone implements a helper class, [`CompilationTestHelper`](https://github.com/google/error-prone/blob/c601758e81723a8efc4671726b8363be7a306dce/test_helpers/src/main/java/com/google/errorprone/CompilationTestHelper.java), to simplify writing bug checkers.
32 |
33 | It is initialized with the checker under test and accepts source code to run the checker on. That code can either be inlined in the test or read from another file.
34 |
35 | The test's author annotates the input code with comments marking where the checker must fire and what it must output.
36 |
37 | `CompilationTestHelper` then runs the checker on the provided code and compares its output with the expectation extracted from the marker comments.
38 |
39 | [Example usage (checker input is inlined)](https://github.com/google/error-prone/blob/c601758e81723a8efc4671726b8363be7a306dce/core/src/test/java/com/google/errorprone/bugpatterns/HashCodeToStringTest.java#L29-L62):
40 |
41 | ```java
42 | public class HashCodeToStringTest {
43 |
44 | private final CompilationTestHelper compilationHelper =
45 | CompilationTestHelper.newInstance(HashCodeToString.class, getClass());
46 |
47 | @Test
48 | public void testPositiveCase() {
49 | compilationHelper
50 | .addSourceLines(
51 | "HashCodeOnly.java",
52 | "public class HashCodeOnly {",
53 | " // BUG: Diagnostic contains: HashCodeToString",
54 | " public int hashCode() {",
55 | " return 0;",
56 | " }",
57 | "}")
58 | .doTest();
59 | }
60 |
61 | @Test
62 | public void negative_bothHashCodeAndToString() {
63 | compilationHelper
64 | .addSourceLines(
65 | "HashCodeAndToString.java",
66 | "public class HashCodeAndToString {",
67 | " public int hashCode() {",
68 | " return 0;",
69 | " }",
70 | " public String toString() {",
71 | " return \"42\";",
72 | " }",
73 | "}")
74 | .doTest();
75 | }
76 | ```
77 |
78 | [Example usage (checker input is read from another file)](https://github.com/google/error-prone/blob/c601758e81723a8efc4671726b8363be7a306dce/core/src/test/java/com/google/errorprone/bugpatterns/ComparableTypeTest.java#L25-L38):
79 |
80 | ```java
81 | public class ComparableTypeTest {
82 | private final CompilationTestHelper compilationHelper =
83 | CompilationTestHelper.newInstance(ComparableType.class, getClass());
84 |
85 | @Test
86 | public void testPositiveCase() {
87 | compilationHelper.addSourceFile("ComparableTypePositiveCases.java").doTest();
88 | }
89 |
90 | @Test
91 | public void testNegativeCase() {
92 | compilationHelper.addSourceFile("ComparableTypeNegativeCases.java").doTest();
93 | }
94 | }
95 | ```
96 |
97 | Unlike typical unit tests that interact with the public interface of the code under test, these Error Prone bug checkers' tests interact with the code under test in a very indirect way. They follow they [black-box approach](https://en.wikipedia.org/wiki/Black-box_testing) and make no assumptions about the checker's implementation.
98 |
99 | ## Implementation details
100 |
101 | `CompilationTestHelper` [uses](https://github.com/google/error-prone/blob/c601758e81723a8efc4671726b8363be7a306dce/test_helpers/src/main/java/com/google/errorprone/CompilationTestHelper.java#L168-L198) the [Builder pattern](https://refactoring.guru/design-patterns/builder/java/example) (not the same Builder as [described in the GoF book!](https://en.wikipedia.org/wiki/Builder_pattern)) to add source code and various configurations:
102 |
103 | ```java
104 | /**
105 | * Adds a source file to the test compilation, from the string content of the file.
106 | *
107 | * The diagnostics expected from compiling the file are inferred from the file contents. For
108 | * each line of the test file that contains the bug marker pattern "// BUG: Diagnostic contains:
109 | * foo", we expect to see a diagnostic on that line containing "foo". For each line of the test
110 | * file that does not contain the bug marker pattern, we expect no diagnostic to be
111 | * generated. You can also use "// BUG: Diagnostic matches: X" in tandem with {@code
112 | * expectErrorMessage("X", "foo")} to allow you to programmatically construct the error message.
113 | *
114 | * @param path a path for the source file
115 | * @param lines the content of the source file
116 | */
117 | public CompilationTestHelper addSourceLines(String path, String... lines) {
118 | this.sources.add(forSourceLines(path, lines));
119 | return this;
120 | }
121 |
122 | /**
123 | * Adds a source file to the test compilation, from an existing resource file.
124 | *
125 | *
See {@link #addSourceLines} for how expected diagnostics should be specified.
126 | *
127 | * @param path the path to the source file
128 | */
129 | public CompilationTestHelper addSourceFile(String path) {
130 | this.sources.add(forResource(clazz, path));
131 | return this;
132 | }
133 | ```
134 |
135 | The main [`doTest` method](https://github.com/google/error-prone/blob/c601758e81723a8efc4671726b8363be7a306dce/test_helpers/src/main/java/com/google/errorprone/CompilationTestHelper.java#L293-L346) that compiles the supplied code and compares the output to the expectations:
136 | ```java
137 | /** Performs a compilation and checks that the diagnostics and result match the expectations. */
138 | public void doTest() {
139 | checkState(!sources.isEmpty(), "No source files to compile");
140 | checkState(!run, "doTest should only be called once");
141 | this.run = true;
142 | Result result = compile();
143 | for (Diagnostic diagnostic : diagnosticHelper.getDiagnostics()) {
144 | if (diagnostic.getCode().contains("error.prone.crash")) {
145 | fail(diagnostic.getMessage(Locale.ENGLISH));
146 | }
147 | }
148 | if (expectNoDiagnostics) {
149 | List> diagnostics = diagnosticHelper.getDiagnostics();
150 | assertWithMessage(
151 | String.format(
152 | "Expected no diagnostics produced, but found %d: %s",
153 | diagnostics.size(), diagnostics))
154 | .that(diagnostics.size())
155 | .isEqualTo(0);
156 | assertWithMessage(
157 | String.format(
158 | "Expected compilation result to be "
159 | + expectedResult.orElse(Result.OK)
160 | + ", but was %s. No diagnostics were emitted."
161 | + " OutputStream from Compiler follows.\n\n%s",
162 | result,
163 | outputStream))
164 | .that(result)
165 | .isEqualTo(expectedResult.orElse(Result.OK));
166 | } else {
167 | for (JavaFileObject source : sources) {
168 | try {
169 | diagnosticHelper.assertHasDiagnosticOnAllMatchingLines(
170 | source, lookForCheckNameInDiagnostic);
171 | } catch (IOException e) {
172 | throw new UncheckedIOException(e);
173 | }
174 | }
175 | assertWithMessage("Unused error keys: " + diagnosticHelper.getUnusedLookupKeys())
176 | .that(diagnosticHelper.getUnusedLookupKeys().isEmpty())
177 | .isTrue();
178 | }
179 |
180 | expectedResult.ifPresent(
181 | expected ->
182 | assertWithMessage(
183 | String.format(
184 | "Expected compilation result %s, but was %s\n%s\n%s",
185 | expected,
186 | result,
187 | Joiner.on('\n').join(diagnosticHelper.getDiagnostics()),
188 | outputStream))
189 | .that(result)
190 | .isEqualTo(expected));
191 | }
192 | ```
193 |
194 | [Extracting markers](https://github.com/google/error-prone/blob/c601758e81723a8efc4671726b8363be7a306dce/test_helpers/src/main/java/com/google/errorprone/DiagnosticTestHelper.java#L275-L353) from code and comparing them to the actual results:
195 |
196 | ```java
197 | /**
198 | * Asserts that the diagnostics contain a diagnostic on each line of the source file that matches
199 | * our bug marker pattern. Parses the bug marker pattern for the specific string to look for in
200 | * the diagnostic.
201 | *
202 | * @param source File in which to find matching lines
203 | */
204 | public void assertHasDiagnosticOnAllMatchingLines(
205 | JavaFileObject source, LookForCheckNameInDiagnostic lookForCheckNameInDiagnostic)
206 | throws IOException {
207 | final List> diagnostics = getDiagnostics();
208 | final LineNumberReader reader =
209 | new LineNumberReader(CharSource.wrap(source.getCharContent(false)).openStream());
210 | do {
211 | String line = reader.readLine();
212 | if (line == null) {
213 | break;
214 | }
215 |
216 | List> predicates = null;
217 | if (line.contains(BUG_MARKER_COMMENT_INLINE)) {
218 | // Diagnostic must contain all patterns from the bug marker comment.
219 | List patterns = extractPatterns(line, reader, BUG_MARKER_COMMENT_INLINE);
220 | predicates = new ArrayList<>(patterns.size());
221 | for (String pattern : patterns) {
222 | predicates.add(new SimpleStringContains(pattern));
223 | }
224 | } else if (line.contains(BUG_MARKER_COMMENT_LOOKUP)) {
225 | int markerLineNumber = reader.getLineNumber();
226 | List lookupKeys = extractPatterns(line, reader, BUG_MARKER_COMMENT_LOOKUP);
227 | predicates = new ArrayList<>(lookupKeys.size());
228 | for (String lookupKey : lookupKeys) {
229 | assertWithMessage(
230 | "No expected error message with key [%s] as expected from line [%s] "
231 | + "with diagnostic [%s]",
232 | lookupKey, markerLineNumber, line.trim())
233 | .that(expectedErrorMsgs.containsKey(lookupKey))
234 | .isTrue();
235 | predicates.add(expectedErrorMsgs.get(lookupKey));
236 | usedLookupKeys.add(lookupKey);
237 | }
238 | }
239 |
240 | if (predicates != null) {
241 | int lineNumber = reader.getLineNumber();
242 | for (Predicate predicate : predicates) {
243 | Matcher>> patternMatcher =
244 | hasItem(diagnosticOnLine(source.toUri(), lineNumber, predicate));
245 | assertWithMessage(
246 | "Did not see an error on line %s matching %s. %s",
247 | lineNumber, predicate, allErrors(diagnostics))
248 | .that(patternMatcher.matches(diagnostics))
249 | .isTrue();
250 | }
251 |
252 | if (checkName != null && lookForCheckNameInDiagnostic == LookForCheckNameInDiagnostic.YES) {
253 | // Diagnostic must contain check name.
254 | Matcher>> checkNameMatcher =
255 | hasItem(
256 | diagnosticOnLine(
257 | source.toUri(), lineNumber, new SimpleStringContains("[" + checkName + "]")));
258 | assertWithMessage(
259 | "Did not see an error on line %s containing [%s]. %s",
260 | lineNumber, checkName, allErrors(diagnostics))
261 | .that(checkNameMatcher.matches(diagnostics))
262 | .isTrue();
263 | }
264 |
265 | } else {
266 | int lineNumber = reader.getLineNumber();
267 | Matcher>> matcher =
268 | hasItem(diagnosticOnLine(source.toUri(), lineNumber));
269 | if (matcher.matches(diagnostics)) {
270 | fail("Saw unexpected error on line " + lineNumber + ". " + allErrors(diagnostics));
271 | }
272 | }
273 | } while (true);
274 | reader.close();
275 | }
276 | ```
277 |
278 | ## Related
279 |
280 | Many related products - linters, bug checkers, etc. - implement very similar patterns. For example, see SonarQube's [CheckVerifier](https://github.com/SonarSource/sonar-java/blob/434f170b9667df33eb7355c0e7e62147c48a7da8/java-checks-testkit/src/main/java/org/sonar/java/checks/verifier/CheckVerifier.java#) or Rubocop's [ExpectOffence](https://github.com/rubocop/rubocop/blob/dc858b7ba893ffeae5edfe7b8012d8f13afd6903/lib/rubocop/rspec/expect_offense.rb).
281 |
282 | Some other Java code analysis tools are built on top of Error Prone, making use of its extensible design. For example, Uber's [NullAway](https://github.com/uber/NullAway). NullAway also uses Error Prone's test helper, e.g. [here](https://github.com/uber/NullAway/blob/067c31dca42a7d2302c3058cb7a626bc02574c39/nullaway/src/test/java/com/uber/nullaway/NullAwayTest.java#L294-L331).
283 |
284 | ## References
285 |
286 | * [GitHub Repo](https://github.com/google/error-prone)
287 | * [Error Prone](https://errorprone.info)
288 | * [Writing a check](https://github.com/google/error-prone/wiki/Writing-a-check)
289 |
290 | ## Copyright notice
291 |
292 | Error Prone is licensed under the [Apache License 2.0](https://github.com/google/error-prone/blob/master/COPYING).
293 |
--------------------------------------------------------------------------------
/_articles/zookeeper-trie.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "ZooKeeper - Trie [Java]"
3 | layout: default
4 | last_modified_date: 2021-07-28T19:29:00+0300
5 | nav_order: 9
6 |
7 | status: PUBLISHED
8 | language: Java
9 | short-title: Trie
10 | project:
11 | name: Apache ZooKeeper
12 | key: zookeeper
13 | home-page: https://github.com/apache/zookeeper
14 | tags: [trie, data-structure, algorithm]
15 | ---
16 |
17 | {% include article-meta.html article=page %}
18 |
19 | ## Context
20 |
21 | Apache ZooKeeper is a centralized service for maintaining configuration information, naming, providing distributed synchronization, and providing group services. ZooKeeper manipulates [znodes](https://zookeeper.apache.org/doc/r3.1.2/zookeeperProgrammers.html#sc_zkDataModel_znodes) - data objects organized hierarchically as in file systems.
22 |
23 | ## Problem
24 |
25 | As a part of the quota management, ZooKeeper needs to find the longest stored prefix for a given path.
26 |
27 | ## Overview
28 |
29 | ZooKeeper implements the [Trie](https://en.wikipedia.org/wiki/Trie) data structure to find the longest stored prefix for a given path.
30 |
31 | The implementation is thread-safe. [`ReadWriteLock`](https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/locks/ReadWriteLock.html) is used - the read lock may be held simultaneously by multiple reader threads, so long as there are no writers. The write lock is exclusive.
32 |
33 | ## Implementation details
34 |
35 | [The implementation](https://github.com/apache/zookeeper/blob/e642a325b91ab829aefa47708c7b4b45811d2d23/zookeeper-server/src/main/java/org/apache/zookeeper/common/PathTrie.java#L34-L354) is rather short and self-explanatory:
36 |
37 | ```java
38 | /**
39 | * a class that implements prefix matching for
40 | * components of a filesystem path. the trie
41 | * looks like a tree with edges mapping to
42 | * the component of a path.
43 | * example /ab/bc/cf would map to a trie
44 | * /
45 | * ab/
46 | * (ab)
47 | * bc/
48 | * /
49 | * (bc)
50 | * cf/
51 | * (cf)
52 | */
53 | public class PathTrie {
54 |
55 | /** Logger for this class */
56 | private static final Logger LOG = LoggerFactory.getLogger(PathTrie.class);
57 |
58 | /** Root node of PathTrie */
59 | private final TrieNode rootNode;
60 |
61 | private final ReadWriteLock lock = new ReentrantReadWriteLock(true);
62 |
63 | private final Lock readLock = lock.readLock();
64 |
65 | private final Lock writeLock = lock.writeLock();
66 |
67 | static class TrieNode {
68 |
69 | final String value;
70 | final Map children;
71 | boolean property;
72 | TrieNode parent;
73 |
74 | /**
75 | * Create a trie node with parent as parameter.
76 | *
77 | * @param parent the parent of this node
78 | * @param value the value stored in this node
79 | */
80 | private TrieNode(TrieNode parent, String value) {
81 | this.value = value;
82 | this.parent = parent;
83 | this.property = false;
84 | this.children = new HashMap<>(4);
85 | }
86 |
87 | /**
88 | * Get the parent of this node.
89 | *
90 | * @return the parent node
91 | */
92 | TrieNode getParent() {
93 | return this.parent;
94 | }
95 |
96 | /**
97 | * set the parent of this node.
98 | *
99 | * @param parent the parent to set to
100 | */
101 | void setParent(TrieNode parent) {
102 | this.parent = parent;
103 | }
104 |
105 | /**
106 | * A property that is set for a node - making it special.
107 | */
108 | void setProperty(boolean prop) {
109 | this.property = prop;
110 | }
111 |
112 | /**
113 | * The property of this node.
114 | *
115 | * @return the property for this node
116 | */
117 | boolean hasProperty() {
118 | return this.property;
119 | }
120 |
121 | /**
122 | * The value stored in this node.
123 | *
124 | * @return the value stored in this node
125 | */
126 | public String getValue() {
127 | return this.value;
128 | }
129 |
130 | /**
131 | * Add a child to the existing node.
132 | *
133 | * @param childName the string name of the child
134 | * @param node the node that is the child
135 | */
136 | void addChild(String childName, TrieNode node) {
137 | this.children.putIfAbsent(childName, node);
138 | }
139 |
140 | /**
141 | * Delete child from this node.
142 | *
143 | * @param childName the name of the child to be deleted
144 | */
145 | void deleteChild(String childName) {
146 | this.children.computeIfPresent(childName, (key, childNode) -> {
147 | // Node no longer has an external property associated
148 | childNode.setProperty(false);
149 |
150 | // Delete it if it has no children (is a leaf node)
151 | if (childNode.isLeafNode()) {
152 | childNode.setParent(null);
153 | return null;
154 | }
155 |
156 | return childNode;
157 | });
158 | }
159 |
160 | /**
161 | * Return the child of a node mapping to the input child name.
162 | *
163 | * @param childName the name of the child
164 | * @return the child of a node
165 | */
166 | TrieNode getChild(String childName) {
167 | return this.children.get(childName);
168 | }
169 |
170 | /**
171 | * Get the list of children of this trienode.
172 | *
173 | * @return A collection containing the node's children
174 | */
175 | Collection getChildren() {
176 | return children.keySet();
177 | }
178 |
179 | /**
180 | * Determine if this node is a leaf (has no children).
181 | *
182 | * @return true if this node is a lead node; otherwise false
183 | */
184 | boolean isLeafNode() {
185 | return children.isEmpty();
186 | }
187 |
188 | @Override
189 | public String toString() {
190 | return "TrieNode [name=" + value + ", property=" + property + ", children=" + children.keySet() + "]";
191 | }
192 |
193 | }
194 |
195 | /**
196 | * Construct a new PathTrie with a root node.
197 | */
198 | public PathTrie() {
199 | this.rootNode = new TrieNode(null, "/");
200 | }
201 |
202 | /**
203 | * Add a path to the path trie. All paths are relative to the root node.
204 | *
205 | * @param path the path to add to the trie
206 | */
207 | public void addPath(final String path) {
208 | Objects.requireNonNull(path, "Path cannot be null");
209 |
210 | if (path.length() == 0) {
211 | throw new IllegalArgumentException("Invalid path: " + path);
212 | }
213 | final String[] pathComponents = split(path);
214 |
215 | writeLock.lock();
216 | try {
217 | TrieNode parent = rootNode;
218 | for (final String part : pathComponents) {
219 | TrieNode child = parent.getChild(part);
220 | if (child == null) {
221 | child = new TrieNode(parent, part);
222 | parent.addChild(part, child);
223 | }
224 | parent = child;
225 | }
226 | parent.setProperty(true);
227 | } finally {
228 | writeLock.unlock();
229 | }
230 | }
231 |
232 | /**
233 | * Delete a path from the trie. All paths are relative to the root node.
234 | *
235 | * @param path the path to be deleted
236 | */
237 | public void deletePath(final String path) {
238 | Objects.requireNonNull(path, "Path cannot be null");
239 |
240 | if (path.length() == 0) {
241 | throw new IllegalArgumentException("Invalid path: " + path);
242 | }
243 | final String[] pathComponents = split(path);
244 |
245 |
246 | writeLock.lock();
247 | try {
248 | TrieNode parent = rootNode;
249 | for (final String part : pathComponents) {
250 | if (parent.getChild(part) == null) {
251 | // the path does not exist
252 | return;
253 | }
254 | parent = parent.getChild(part);
255 | LOG.debug("{}", parent);
256 | }
257 |
258 | final TrieNode realParent = parent.getParent();
259 | realParent.deleteChild(parent.getValue());
260 | } finally {
261 | writeLock.unlock();
262 | }
263 | }
264 |
265 | /**
266 | * Return true if the given path exists in the trie, otherwise return false;
267 | * All paths are relative to the root node.
268 | *
269 | * @param path the input path
270 | * @return the largest prefix for the
271 | */
272 | public boolean existsNode(final String path) {
273 | Objects.requireNonNull(path, "Path cannot be null");
274 |
275 | if (path.length() == 0) {
276 | throw new IllegalArgumentException("Invalid path: " + path);
277 | }
278 | final String[] pathComponents = split(path);
279 |
280 | readLock.lock();
281 | try {
282 | TrieNode parent = rootNode;
283 | for (final String part : pathComponents) {
284 | if (parent.getChild(part) == null) {
285 | // the path does not exist
286 | return false;
287 | }
288 | parent = parent.getChild(part);
289 | LOG.debug("{}", parent);
290 | }
291 | } finally {
292 | readLock.unlock();
293 | }
294 | return true;
295 | }
296 |
297 | /**
298 | * Return the largest prefix for the input path. All paths are relative to the
299 | * root node.
300 | *
301 | * @param path the input path
302 | * @return the largest prefix for the input path
303 | */
304 | public String findMaxPrefix(final String path) {
305 | Objects.requireNonNull(path, "Path cannot be null");
306 |
307 | final String[] pathComponents = split(path);
308 |
309 | readLock.lock();
310 | try {
311 | TrieNode parent = rootNode;
312 | TrieNode deepestPropertyNode = null;
313 | for (final String element : pathComponents) {
314 | parent = parent.getChild(element);
315 | if (parent == null) {
316 | LOG.debug("{}", element);
317 | break;
318 | }
319 | if (parent.hasProperty()) {
320 | deepestPropertyNode = parent;
321 | }
322 | }
323 |
324 | if (deepestPropertyNode == null) {
325 | return "/";
326 | }
327 |
328 | final Deque treePath = new ArrayDeque<>();
329 | TrieNode node = deepestPropertyNode;
330 | while (node != this.rootNode) {
331 | treePath.offerFirst(node.getValue());
332 | node = node.parent;
333 | }
334 | return "/" + String.join("/", treePath);
335 | } finally {
336 | readLock.unlock();
337 | }
338 | }
339 |
340 | /**
341 | * Clear all nodes in the trie.
342 | */
343 | public void clear() {
344 | writeLock.lock();
345 | try {
346 | rootNode.getChildren().clear();
347 | } finally {
348 | writeLock.unlock();
349 | }
350 | }
351 |
352 | private static String[] split(final String path){
353 | return Stream.of(path.split("/"))
354 | .filter(t -> !t.trim().isEmpty())
355 | .toArray(String[]::new);
356 | }
357 |
358 | }
359 | ```
360 |
361 | ## Testing
362 |
363 | [PathTrieTest](https://github.com/apache/zookeeper/blob/e642a325b91ab829aefa47708c7b4b45811d2d23/zookeeper-server/src/test/java/org/apache/zookeeper/common/PathTrieTest.java) covers all public methods of `PathTrie`.
364 |
365 | For instance, [tests for `findMaxPrexix`]():
366 |
367 | ```java
368 | @Test
369 | public void findMaxPrefixNullPath() {
370 | assertThrows(NullPointerException.class, () -> {
371 | this.pathTrie.findMaxPrefix(null);
372 | });
373 | }
374 |
375 | @Test
376 | public void findMaxPrefixRootPath() {
377 | assertEquals("/", this.pathTrie.findMaxPrefix("/"));
378 | }
379 |
380 | @Test
381 | public void findMaxPrefixChildren() {
382 | this.pathTrie.addPath("node1");
383 | this.pathTrie.addPath("node1/node2");
384 | this.pathTrie.addPath("node1/node3");
385 |
386 | assertEquals("/node1", this.pathTrie.findMaxPrefix("/node1"));
387 | assertEquals("/node1/node2", this.pathTrie.findMaxPrefix("/node1/node2"));
388 | assertEquals("/node1/node3", this.pathTrie.findMaxPrefix("/node1/node3"));
389 | }
390 |
391 | @Test
392 | public void findMaxPrefixChildrenPrefix() {
393 | this.pathTrie.addPath("node1");
394 |
395 | assertEquals("/node1", this.pathTrie.findMaxPrefix("/node1/node2"));
396 | assertEquals("/node1", this.pathTrie.findMaxPrefix("/node1/node3"));
397 | }
398 | ```
399 |
400 | ## Observations
401 |
402 | * [Deques](https://en.wikipedia.org/wiki/Double-ended_queue) [are used](https://github.com/apache/zookeeper/blob/e642a325b91ab829aefa47708c7b4b45811d2d23/zookeeper-server/src/main/java/org/apache/zookeeper/common/PathTrie.java#L324-L330) to temporarily store values in paths from nodes up to the root. Deques are designed to support element insertion and removal at both ends, but this implementation only adds elements to the front and never removes elements. So a simple `LinkedList` would do. However, `ArrayDeque` may be more efficient.
403 |
404 | ## References
405 |
406 | * [GitHub repo](https://github.com/apache/zookeeper)
407 | * [Trie on Wikipedia](https://en.wikipedia.org/wiki/Trie)
408 |
409 | ## Copyright notice
410 |
411 | Zookeeper is licensed under the [Apache License 2.0](https://github.com/apache/zookeeper/blob/master/LICENSE.txt).
412 |
--------------------------------------------------------------------------------