001: /**
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */package org.apache.solr.search;
017:
018: import org.apache.solr.core.SolrInfoMBean;
019:
020: import java.util.Map;
021: import java.util.logging.Logger;
022: import java.io.IOException;
023:
024: /**
025: * Primary API for dealing with Solr's internal caches.
026: *
027: * @author yonik
028: * @version $Id: SolrCache.java 533176 2007-04-27 17:43:34Z otis $
029: */
030: public interface SolrCache extends SolrInfoMBean {
031: public final static Logger log = Logger.getLogger(SolrCache.class
032: .getName());
033:
034: /**
035: * The initialization routine. Instance specific arguments are passed in
036: * the <code>args</code> map.
037: * <p>
038: * The persistence object will exist across different lifetimes of similar caches.
039: * For example, all filter caches will share the same persistence object, sometimes
040: * at the same time (it must be threadsafe). If null is passed, then the cache
041: * implementation should create and return a new persistence object. If not null,
042: * the passed in object should be returned again.
043: * <p>
044: * Since it will exist across the lifetime of many caches, care should be taken to
045: * not reference any particular cache instance and prevent it from being
046: * garbage collected (no using inner classes unless they are static).
047: * <p>
048: * The persistence object is designed to be used as a way for statistics
049: * to accumulate across all instances of the same type of cache, however the
050: * object may be of any type desired by the cache implementation.
051: * <p>
052: * The {@link CacheRegenerator} is what the cache uses during auto-warming to
053: * renenerate an item in the new cache from an entry in the old cache.
054: *
055: */
056: public Object init(Map args, Object persistence,
057: CacheRegenerator regenerator);
058:
059: // I don't think we need a factory for faster creation given that these
060: // will be associated with slow-to-create SolrIndexSearchers.
061: // change to NamedList when other plugins do?
062:
063: /**
064: * Name the Cache can be referenced with by SolrRequestHandlers.
065: *
066: * This method must return the identifier that the Cache instance
067: * expects SolrRequestHandlers to use when requesting access to it
068: * from the SolrIndexSearcher. It is <strong>strongly</strong>
069: * recommended that this method return the value of the "name"
070: * parameter from the init args.
071: *
072: * :TODO: verify this.
073: */
074: public String name();
075:
076: // Should SolrCache just extend the java.util.Map interface?
077: // Following the conventions of the java.util.Map interface in any case.
078:
079: /** :TODO: copy from Map */
080: public int size();
081:
082: /** :TODO: copy from Map */
083: public Object put(Object key, Object value);
084:
085: /** :TODO: copy from Map */
086: public Object get(Object key);
087:
088: /** :TODO: copy from Map */
089: public void clear();
090:
091: /**
092: * Enumeration of possible States for cache instances.
093: * :TODO: only state that seems to ever be set is LIVE ?
094: */
095: public enum State {
096: /** :TODO */
097: CREATED,
098: /** :TODO */
099: STATICWARMING,
100: /** :TODO */
101: AUTOWARMING,
102: /** :TODO */
103: LIVE
104: }
105:
106: /**
107: * Set different cache states.
108: * The state a cache is in can have an effect on how statistics are kept.
109: * The cache user (SolrIndexSearcher) will take care of switching
110: * cache states.
111: */
112: public void setState(State state);
113:
114: /**
115: * Returns the last State set on this instance
116: *
117: * @see #setState
118: */
119: public State getState();
120:
121: /**
122: * Warm this cache associated with <code>searcher</code> using the <code>old</code>
123: * cache object. <code>this</code> and <code>old</code> will have the same concrete type.
124: */
125: void warm(SolrIndexSearcher searcher, SolrCache old)
126: throws IOException;
127:
128: // Q: an alternative to passing the searcher here would be to pass it in
129: // init and have the cache implementation save it.
130:
131: /** Frees any non-memory resources */
132: public void close();
133:
134: }
|