Key.java
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.maven.di;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.util.Objects;
import org.apache.maven.api.annotations.Nullable;
import org.apache.maven.di.impl.ReflectionUtils;
import org.apache.maven.di.impl.Types;
/**
* A binding key that uniquely identifies a dependency in the injection system.
* <p>
* Keys combine a type with an optional qualifier to uniquely identify dependencies
* within the injection system. They also serve as type tokens, allowing preservation
* of generic type information at runtime.
* <p>
* Example usage:
* <pre>
* // Simple key for a type
* Key<Service> simple = Key.of(Service.class);
*
* // Key with generic type information
* Key<List<String>> generic = new Key<List<String>>(){};
*
* // Key with qualifier
* Key<Service> qualified = Key.of(Service.class, "primary");
* </pre>
*
* @param <T> The type this key represents
* @since 4.0.0
*/
public abstract class Key<T> {
private final Type type;
private final @Nullable Object qualifier;
private int hash;
protected Key() {
this(null);
}
protected Key(@Nullable Object qualifier) {
this.type = Types.simplifyType(getTypeParameter());
this.qualifier = qualifier;
}
protected Key(Type type, @Nullable Object qualifier) {
this.type = Types.simplifyType(type);
this.qualifier = qualifier;
}
static final class KeyImpl<T> extends Key<T> {
KeyImpl(Type type, Object qualifier) {
super(type, qualifier);
}
}
/**
* Creates a new Key instance for the specified type.
*
* @param <T> the type parameter
* @param type the Class object representing the type
* @return a new Key instance
* @throws NullPointerException if type is null
*/
public static <T> Key<T> of(Class<T> type) {
return new KeyImpl<>(type, null);
}
/**
* Creates a new Key instance for the specified type with a qualifier.
*
* @param <T> the type parameter
* @param type the Class object representing the type
* @param qualifier the qualifier object (typically an annotation instance)
* @return a new Key instance
* @throws NullPointerException if type is null
*/
public static <T> Key<T> of(Class<T> type, @Nullable Object qualifier) {
return new KeyImpl<>(type, qualifier);
}
public static <T> Key<T> ofType(Type type) {
return new KeyImpl<>(type, null);
}
public static <T> Key<T> ofType(Type type, @Nullable Object qualifier) {
return new KeyImpl<>(type, qualifier);
}
private Type getTypeParameter() {
// this cannot possibly fail so not even a check here
Type typeArgument = ((ParameterizedType) getClass().getGenericSuperclass()).getActualTypeArguments()[0];
Object outerInstance = ReflectionUtils.getOuterClassInstance(this);
// // the outer instance is null in static context
return outerInstance != null
? Types.bind(typeArgument, Types.getAllTypeBindings(outerInstance.getClass()))
: typeArgument;
}
/**
* Returns the actual type represented by this key.
* <p>
* This includes full generic type information if available.
*
* @return the type represented by this key
*/
public Type getType() {
return type;
}
/**
* A shortcut for <code>{@link Types#getRawType(Type)}(key.getType())</code>.
* Also casts the result to a properly parameterized class.
*/
@SuppressWarnings("unchecked")
public Class<T> getRawType() {
return (Class<T>) Types.getRawType(type);
}
/**
* Returns a type parameter of the underlying type wrapped as a key with no qualifier.
*
* @throws IllegalStateException when underlying type is not a parameterized one.
*/
public <U> Key<U> getTypeParameter(int index) {
if (type instanceof ParameterizedType parameterizedType) {
return new KeyImpl<>(parameterizedType.getActualTypeArguments()[index], null);
}
throw new IllegalStateException("Expected type from key " + getDisplayString() + " to be parameterized");
}
/**
* Returns the qualifier associated with this key, if any.
*
* @return the qualifier object or null if none exists
*/
public @Nullable Object getQualifier() {
return qualifier;
}
/**
* Returns an underlying type with display string formatting (package names stripped)
* and prepended qualifier display string if this key has a qualifier.
*/
public String getDisplayString() {
StringBuilder result = new StringBuilder();
if (qualifier instanceof String s) {
if (s.isEmpty()) {
result.append("@Named ");
} else {
result.append("@Named(\"").append(s).append("\") ");
}
} else if (qualifier != null) {
ReflectionUtils.getDisplayString(result, qualifier);
result.append(" ");
}
result.append(ReflectionUtils.getDisplayName(type));
return result.toString();
}
@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (o instanceof Key<?> that) {
return type.equals(that.type) && Objects.equals(qualifier, that.qualifier);
} else {
return false;
}
}
@Override
public int hashCode() {
int hashCode = hash;
if (hashCode == 0) {
hash = 31 * type.hashCode() + (qualifier == null ? 0 : qualifier.hashCode());
}
return hash;
}
@Override
public String toString() {
return getDisplayString();
}
}