Introduce the concept of ProductAwareBuilder

A ProductAwareBuilder is an builder which can act as a proxy
for its product in collections (obviously provided it is not
mutated while its used this way).

This functionality is useful for implemeting caches, where
the toInstance() call can be skipped as long as there is an
existing equal object.

Change-Id: I24c98dcb41491ba6265b373c34667e2a0ddfed86
Signed-off-by: Robert Varga <rovarga@cisco.com>

diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/ProductAwareBuilder.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/ProductAwareBuilder.java
new file mode 100644 (file)
index 0000000..b2c2d04
--- /dev/null
+++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/ProductAwareBuilder.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.concepts;
+
+/**
+ * An extension of the {@link Builder} concept which allows an implementation
+ * of this interface to be used in collections instead of the product. Given
+ * the mutable nature of Builders, this has to be done very carefully.
+ *
+ * @param <P> Product type
+ */
+public interface ProductAwareBuilder<P> extends Builder<P> {
+       /**
+        * Return the hash code of the product. This has to be equivalent
+        * of calling {@link #toInstance()}.{@link #hashCode()}.
+        *
+        * @return the hash code of the product.
+        */
+       int productHashCode();
+
+       /**
+        * Check whether an instance of the product that would be created
+        * by the builder is equal to an existing instance. This has to
+        * be equivalent of calling {@link #toInstance()}.{@link #equals(Object)}.
+        *
+        * @param product Product instance
+        * @return Return true if the product is equal to the would-be
+        *         product of the builder.
+        */
+       boolean productEquals(Object product);
+}