| /* |
| * 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.solr.search; |
| |
| import java.util.Map; |
| |
| import org.apache.solr.core.SolrInfoBean; |
| import org.apache.solr.metrics.SolrMetricProducer; |
| |
| |
| /** |
| * Primary API for dealing with Solr's internal caches. |
| */ |
| public interface SolrCache<K,V> extends SolrInfoBean, SolrMetricProducer { |
| String TYPE = "cache"; |
| |
| String HIT_RATIO_PARAM = "hitratio"; |
| String HITS_PARAM = "hits"; |
| String INSERTS_PARAM = "inserts"; |
| String EVICTIONS_PARAM = "evictions"; |
| String LOOKUPS_PARAM = "lookups"; |
| String SIZE_PARAM = "size"; |
| String MAX_SIZE_PARAM = "maxSize"; |
| String RAM_BYTES_USED_PARAM = "ramBytesUsed"; |
| String MAX_RAM_MB_PARAM = "maxRamMB"; |
| String MAX_IDLE_TIME_PARAM = "maxIdleTime"; |
| |
| /** |
| * The initialization routine. Instance specific arguments are passed in |
| * the <code>args</code> map. |
| * <p> |
| * The persistence object will exist across different lifetimes of similar caches. |
| * For example, all filter caches will share the same persistence object, sometimes |
| * at the same time (it must be thread-safe). If null is passed, then the cache |
| * implementation should create and return a new persistence object. If not null, |
| * the passed in object should be returned again. |
| * <p> |
| * Since it will exist across the lifetime of many caches, care should be taken to |
| * not reference any particular cache instance and prevent it from being |
| * garbage collected (no using inner classes unless they are static). |
| * <p> |
| * The persistence object is designed to be used as a way for statistics |
| * to accumulate across all instances of the same type of cache, however the |
| * object may be of any type desired by the cache implementation. |
| * <p> |
| * The {@link CacheRegenerator} is what the cache uses during auto-warming to |
| * regenerate an item in the new cache from an entry in the old cache. |
| * |
| */ |
| Object init(Map args, Object persistence, CacheRegenerator regenerator); |
| // I don't think we need a factory for faster creation given that these |
| // will be associated with slow-to-create SolrIndexSearchers. |
| // change to NamedList when other plugins do? |
| |
| /** |
| * Name the Cache can be referenced with by SolrRequestHandlers. |
| * |
| * This method must return the identifier that the Cache instance |
| * expects SolrRequestHandlers to use when requesting access to it |
| * from the SolrIndexSearcher. It is <strong>strongly</strong> |
| * recommended that this method return the value of the "name" |
| * parameter from the init args. |
| * |
| * :TODO: verify this. |
| */ |
| String name(); |
| |
| |
| // Should SolrCache just extend the java.util.Map interface? |
| // Following the conventions of the java.util.Map interface in any case. |
| |
| /** :TODO: copy from Map */ |
| int size(); |
| |
| /** :TODO: copy from Map */ |
| V put(K key, V value); |
| |
| /** :TODO: copy from Map */ |
| V get(K key); |
| |
| /** :TODO: copy from Map */ |
| void clear(); |
| |
| /** |
| * Enumeration of possible States for cache instances. |
| * :TODO: only state that seems to ever be set is LIVE ? |
| */ |
| enum State { |
| /** :TODO */ |
| CREATED, |
| /** :TODO */ |
| STATICWARMING, |
| /** :TODO */ |
| AUTOWARMING, |
| /** :TODO */ |
| LIVE |
| } |
| |
| /** |
| * Set different cache states. |
| * The state a cache is in can have an effect on how statistics are kept. |
| * The cache user (SolrIndexSearcher) will take care of switching |
| * cache states. |
| */ |
| void setState(State state); |
| |
| /** |
| * Returns the last State set on this instance |
| * |
| * @see #setState |
| */ |
| State getState(); |
| |
| /** |
| * Warm this cache associated with <code>searcher</code> using the <code>old</code> |
| * cache object. <code>this</code> and <code>old</code> will have the same concrete type. |
| */ |
| void warm(SolrIndexSearcher searcher, SolrCache<K,V> old); |
| // Q: an alternative to passing the searcher here would be to pass it in |
| // init and have the cache implementation save it. |
| |
| |
| /** Frees any non-memory resources */ |
| void close(); |
| |
| /** Returns maximum size limit (number of items) if set and supported, -1 otherwise. */ |
| int getMaxSize(); |
| |
| /** Set maximum size limit (number of items), or -1 for unlimited. Note: this has effect |
| * only on implementations that support it, it's a no-op otherwise |
| */ |
| void setMaxSize(int maxSize); |
| |
| /** Returns maximum size limit (in MB) if set and supported, -1 otherwise. */ |
| int getMaxRamMB(); |
| |
| /** Set maximum size limit (in MB), or -1 for unlimited. Note: this has effect |
| * only on implementations that support it, it's a no-op otherwise. |
| */ |
| void setMaxRamMB(int maxRamMB); |
| } |