HashKey

/*
 * 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.juneau.commons.collections;

import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.Utils.*;

import java.util.*;

/**
 * Represents a composite key composed of multiple values, suitable for use as a key in hash-based collections.
 *
 * <p>
 * This class provides an immutable, thread-safe way to create composite keys from multiple values.
 * It's commonly used for caching scenarios where you need to uniquely identify objects based on
 * multiple configuration parameters or attributes.
 *
 * <h5 class='section'>Usage Pattern:</h5>
 * <p class='bjava'>
 * 	<jc>// Create a composite key from multiple values</jc>
 * 	HashKey <jv>key</jv> = HashKey.<jsm>of</jsm>(
 * 		<js>"config1"</js>,
 * 		<js>"config2"</js>,
 * 		<jk>true</jk>,
 * 		<jk>42</jk>
 * 	);
 *
 * 	<jc>// Use as a key in a cache or map</jc>
 * 	Map&lt;HashKey, MyObject&gt; <jv>cache</jv> = <jk>new</jk> HashMap&lt;&gt;();
 * 	<jv>cache</jv>.<jsm>put</jsm>(<jv>key</jv>, <jv>myObject</jv>);
 *
 * 	<jc>// Retrieve using an equivalent key</jc>
 * 	HashKey <jv>lookupKey</jv> = HashKey.<jsm>of</jsm>(<js>"config1"</js>, <js>"config2"</js>, <jk>true</jk>, <jk>42</jk>);
 * 	MyObject <jv>cached</jv> = <jv>cache</jv>.<jsm>get</jsm>(<jv>lookupKey</jv>);  <jc>// Returns myObject</jc>
 * </p>
 *
 * <h5 class='section'>Important Notes:</h5>
 * <ul class='spaced-list'>
 * 	<li>
 * 		<b>All relevant values must be included</b> - When using {@code HashKey} for caching, ensure all
 * 		values that affect the object's identity are included. Missing values can cause different objects
 * 		to incorrectly share the same cache entry.
 * 	<li>
 * 		<b>Order matters</b> - The order of arguments in {@link #of(Object...)} is significant.
 * 		Two keys with the same values in different orders will not be equal.
 * 	<li>
 * 		<b>Immutable</b> - Once created, a {@code HashKey} cannot be modified. This ensures keys
 * 		remain stable when used in hash-based collections.
 * 	<li>
 * 		<b>Thread-safe</b> - This class is thread-safe and can be safely used as keys in concurrent
 * 		collections and caches.
 * 	<li>
 * 		<b>Null values are supported</b> - {@code null} values can be included in the key and are
 * 		handled correctly in equality comparisons.
 * </ul>
 *
 * <h5 class='section'>Example:</h5>
 * <p class='bjava'>
 * 	<jc>// Create keys for caching based on configuration</jc>
 * 	HashKey <jv>key1</jv> = HashKey.<jsm>of</jsm>(<js>"json"</js>, <jk>true</jk>, <jk>false</jk>);
 * 	HashKey <jv>key2</jv> = HashKey.<jsm>of</jsm>(<js>"json"</js>, <jk>true</jk>, <jk>false</jk>);
 * 	HashKey <jv>key3</jv> = HashKey.<jsm>of</jsm>(<js>"json"</js>, <jk>true</jk>, <jk>true</jk>);
 *
 * 	<jc>// key1 and key2 are equal (same values in same order)</jc>
 * 	<jv>key1</jv>.<jsm>equals</jsm>(<jv>key2</jv>);  <jc>// true</jc>
 * 	<jv>key1</jv>.<jsm>hashCode</jsm>() == <jv>key2</jv>.<jsm>hashCode</jsm>();  <jc>// true</jc>
 *
 * 	<jc>// key1 and key3 are different (different values)</jc>
 * 	<jv>key1</jv>.<jsm>equals</jsm>(<jv>key3</jv>);  <jc>// false</jc>
 *
 * 	<jc>// Use in a cache</jc>
 * 	Cache&lt;HashKey, Processor&gt; <jv>processorCache</jv> = Cache.<jsm>create</jsm>();
 * 	<jv>processorCache</jv>.<jsm>put</jsm>(<jv>key1</jv>, <jk>new</jk> JsonProcessor());
 * 	Processor <jv>p</jv> = <jv>processorCache</jv>.<jsm>get</jsm>(<jv>key2</jv>);  <jc>// Returns cached instance</jc>
 * </p>
 */
public class HashKey {

	/**
	 * Creates a new hash key from the specified values.
	 *
	 * <p>
	 * The order of arguments is significant - two calls with the same values in the same order
	 * will produce equal {@code HashKey} instances, while different orders or values will produce
	 * different keys.
	 *
	 * <h5 class='section'>Example:</h5>
	 * <p class='bjava'>
	 * 	HashKey <jv>key1</jv> = HashKey.<jsm>of</jsm>(<js>"a"</js>, <js>"b"</js>, <jk>true</jk>);
	 * 	HashKey <jv>key2</jv> = HashKey.<jsm>of</jsm>(<js>"a"</js>, <js>"b"</js>, <jk>true</jk>);
	 * 	<jv>key1</jv>.<jsm>equals</jsm>(<jv>key2</jv>);  <jc>// true</jc>
	 *
	 * 	HashKey <jv>key3</jv> = HashKey.<jsm>of</jsm>(<js>"a"</js>, <js>"b"</js>, <jk>false</jk>);
	 * 	<jv>key1</jv>.<jsm>equals</jsm>(<jv>key3</jv>);  <jc>// false</jc>
	 *
	 * 	<jc>// Order matters</jc>
	 * 	HashKey <jv>key4</jv> = HashKey.<jsm>of</jsm>(<js>"b"</js>, <js>"a"</js>, <jk>true</jk>);
	 * 	<jv>key1</jv>.<jsm>equals</jsm>(<jv>key4</jv>);  <jc>// false (different order)</jc>
	 * </p>
	 *
	 * @param array The values that compose this composite key.
	 * 	All values that affect the key's identity should be included.
	 * 	<br>Can be empty (produces a key representing no values).
	 * 	<br>Can contain {@code null} values (handled correctly in equality comparisons).
	 * @return A new immutable hash key instance.
	 */
	public static HashKey of(Object...array) {
		return new HashKey(array);
	}

	private final int hashCode;
	private final Object[] array;

	HashKey(Object[] array) {
		this.array = array;
		this.hashCode = Arrays.deepHashCode(array);
	}

	/**
	 * Compares this hash key with another object for equality.
	 *
	 * <p>
	 * Two {@code HashKey} instances are considered equal if they contain the same values in the same order.
	 * The comparison uses deep equality checking for array elements via {@link org.apache.juneau.commons.utils.Utils#eq(Object, Object)}.
	 *
	 * <p>
	 * This method does not perform null or type checking - it assumes the caller has verified the object
	 * is a non-null {@code HashKey} instance. Passing {@code null} or a non-{@code HashKey} object will
	 * result in a {@code ClassCastException} or {@code NullPointerException}.
	 *
	 * @param o The object to compare with (must be a non-null {@code HashKey} instance).
	 * @return {@code true} if the objects are equal, {@code false} otherwise.
	 */
	@Override
	public boolean equals(Object o) {
		if (o == null || !(o instanceof HashKey))
			return false;
		var x = (HashKey)o;
		if (array.length != x.array.length)
			return false;
		for (var i = 0; i < array.length; i++)
			if (neq(array[i], x.array[i]))
				return false;
		return true;
	}

	/**
	 * Returns the hash code for this hash key.
	 *
	 * <p>
	 * The hash code is computed from all values in the key using {@link Arrays#deepHashCode(Object[])}.
	 * This ensures that equal keys have equal hash codes, making {@code HashKey} suitable for use
	 * as keys in hash-based collections like {@link java.util.HashMap} and {@link java.util.HashSet}.
	 * Arrays with the same contents (but different references) will produce the same hash code.
	 *
	 * @return The hash code value for this object.
	 */
	@Override
	public int hashCode() {
		return hashCode;
	}

	protected FluentMap<String,Object> properties() {
		// @formatter:off
		return filteredBeanPropertyMap()
			.a("hashCode", hashCode())
			.a("array", array);
		// @formatter:on
	}

	@Override /* Overridden from Object */
	public String toString() {
		return r(properties());
	}
}