2 * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
8 package org.opendaylight.yangtools.objcache;
10 import javax.annotation.Nonnull;
11 import javax.annotation.Nullable;
12 import org.opendaylight.yangtools.concepts.Immutable;
13 import org.opendaylight.yangtools.concepts.ProductAwareBuilder;
16 * A cache of objects. Caches are useful for reducing memory overhead
17 * stemming from multiple copies of identical objects -- by putting
18 * a cache in the instantiation path, one can expend some memory on
19 * indexes and spend some CPU cycles on walking the index to potentially
20 * end up with a reused object.
22 * Note that the cached objects should really be semantically {@link Immutable}.
23 * This interface does not enforce that interface contract simply because
24 * there are third-party objects which fulfill this contract.
26 public interface ObjectCache {
28 * Get a reference for an object which is equal to specified object.
29 * The cache is free return either a cached instance, or retain the
30 * object and return it back.
32 * @param <T> object type
33 * @param object Requested object, may be null
34 * @return Reference to an object which is equal to the one passed in.
35 * If @object was @null, this method returns @null.
37 <T> T getReference(@Nullable T object);
40 * Get a reference to an object equal to the product of a builder.
41 * The builder is expected to remain constant while this method
42 * executes. Unlike {@link #getReference(Object)}, this method has
43 * the potential of completely eliding the product instantiation.
45 * @param <P> produced object type
46 * @param <B> builder type
47 * @param builder Builder instance, may not be null
48 * @return Result of builder's toInstance() product, or an equal
51 <B extends ProductAwareBuilder<P>, P> P getProduct(@Nonnull B builder);