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.eclipse.aether;
20
21 import java.util.Arrays;
22
23 import static java.util.Objects.requireNonNull;
24
25 /**
26 * A helper class to create keys, to be used with {@link SessionData} and {@link RepositoryCache} instances as keys.
27 * Resolver codebase started with {@link String} keys, that are generally perfect for keys in these constructs, as
28 * long as they are used by components loaded once in system. As we saw, some subsystems like transports can be
29 * loaded multiple times. For example, in case of Maven, some transport may be present in Maven core, but also loaded up
30 * by some extension. In this case, key should distinguish between their {@link ClassLoader}s.
31 * <p>
32 * It is this class caller responsibility to use proper objects as keys, this class merely helps one to create composite
33 * keys out of object instances that are expected to be anyway good candidates as key. Examples of these objects are
34 * {@link String} instances but also {@link Class} instances, and many other types also usable as keys.
35 * <p>
36 * Important: never forget to perform {@code null}-check, when getting cache from {@link RepositorySystemSession#getCache()}
37 * method as it may return {@code null}, when cache is disabled session-wise.
38 * <p>
39 * Historical note: As mentioned above, use of {@link String} instances for keys is perfect match, and it worked from
40 * very start. But, as use cases got more and more complex and keys used started to be constructed in more and more
41 * sophisticated ways, but were still {@link String} instances. Believe, or not, the sole purpose of string keys
42 * was easier debugging. By using this helper class, this convenience should remain.
43 *
44 * @see RepositorySystemSession#getData()
45 * @see SessionData
46 * @see RepositorySystemSession#getCache()
47 * @see RepositoryCache
48 * @since 2.0.19
49 */
50 public final class Keys {
51 private Keys() {}
52
53 /**
54 * Creates object instance usable as key in session data and cache. Objects passed to this method may or may
55 * not implement equals/hashCode, but it is responsibility of caller to understand what is she or he doing.
56 * <p>
57 * If the first element of key elements is an object instance that was created by this method, creation of
58 * "subkeys" happens, where original key elements expanded from first element and are concatenated with new ones.
59 * This expansion happens <em>only, if the first key element was already a key created by this class</em>.
60 * If the arguments contain only one argument, and it is an object instance that was created by this method,
61 * the passed in instance is returned unmodified.
62 * <p>
63 * Based on what kind of elements are used, one can create multiple kind of keys:
64 * <ul>
65 * <li>To create <em>globally matched keys</em>, preferred is to use {@link String} key elements</li>
66 * <li>To create <em>ClassLoader wide matched keys</em>, make sure at least one key element is {@link Class} that needs to be scoped to ClassLoader</li>
67 * <li>To create <em>private, matched by creator only keys</em>, make sure to have one key element, that requires instance equality matching, and there is no other same instance of element</li>
68 * </ul>
69 *
70 * @param keys The key elements, it may not be {@code null} and may not have zero elements.
71 * @return An object instance usable as key.
72 */
73 public static Object of(Object... keys) {
74 requireNonNull(keys, "keys cannot be null");
75 if (keys.length == 0) {
76 throw new IllegalArgumentException("keys must have at least one element");
77 } else if (keys[0] instanceof Key) {
78 Key head = (Key) keys[0];
79 if (keys.length == 1) {
80 return head;
81 } else {
82 return new Key(concat(head.keys, Arrays.copyOfRange(keys, 1, keys.length)));
83 }
84 } else {
85 return new Key(keys);
86 }
87 }
88
89 private static final class Key {
90 private final Object[] keys;
91 private final int hashCode;
92
93 private Key(Object[] keys) {
94 this.keys = keys.clone();
95 this.hashCode = Arrays.hashCode(keys);
96 }
97
98 @Override
99 public boolean equals(Object obj) {
100 if (this == obj) {
101 return true;
102 } else if (!(obj instanceof Key)) {
103 return false;
104 }
105 Key that = (Key) obj;
106 return Arrays.equals(keys, that.keys);
107 }
108
109 @Override
110 public int hashCode() {
111 return hashCode;
112 }
113
114 @Override
115 public String toString() {
116 return Arrays.toString(keys);
117 }
118 }
119
120 private static Object[] concat(Object[] one, Object[] two) {
121 Object[] result = Arrays.copyOf(one, one.length + two.length);
122 System.arraycopy(two, 0, result, one.length, two.length);
123 return result;
124 }
125 }