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;
13 import org.opendaylight.yangtools.concepts.Immutable;
14 import org.opendaylight.yangtools.concepts.ProductAwareBuilder;
17 * A cache of objects. Caches are useful for reducing memory overhead
18 * stemming from multiple copies of identical objects -- by putting
19 * a cache in the instantiation path, one can expend some memory on
20 * indexes and spend some CPU cycles on walking the index to potentially
21 * end up with a reused object.
23 * Note that the cached objects should really be semantically {@link Immutable}.
24 * This interface does not enforce that interface contract simply because
25 * there are third-party objects which fulfill this contract.
27 public interface ObjectCache {
29 * Get a reference for an object which is equal to specified object.
30 * The cache is free return either a cached instance, or retain the
31 * object and return it back.
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 builder Builder instance, may not be null
46 * @return Result of builder's toInstance() product, or an equal
49 <B extends ProductAwareBuilder<P>, P> P getProduct(@Nonnull B builder);