Java tutorial
/* * 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.lucene.facet.taxonomy; import java.io.Closeable; import java.io.IOException; import java.util.Map; import java.util.concurrent.atomic.AtomicInteger; import org.apache.lucene.store.AlreadyClosedException; /** * TaxonomyReader is the read-only interface with which the faceted-search * library uses the taxonomy during search time. * <P> * A TaxonomyReader holds a list of categories. Each category has a serial * number which we call an "ordinal", and a hierarchical "path" name: * <UL> * <LI> * The ordinal is an integer that starts at 0 for the first category (which is * always the root category), and grows contiguously as more categories are * added; Note that once a category is added, it can never be deleted. * <LI> * The path is a CategoryPath object specifying the category's position in the * hierarchy. * </UL> * <B>Notes about concurrent access to the taxonomy:</B> * <P> * An implementation must allow multiple readers to be active concurrently * with a single writer. Readers follow so-called "point in time" semantics, * i.e., a TaxonomyReader object will only see taxonomy entries which were * available at the time it was created. What the writer writes is only * available to (new) readers after the writer's commit() is called. * <P> * In faceted search, two separate indices are used: the main Lucene index, * and the taxonomy. Because the main index refers to the categories listed * in the taxonomy, it is important to open the taxonomy *after* opening the * main index, and it is also necessary to reopen() the taxonomy after * reopen()ing the main index. * <P> * This order is important, otherwise it would be possible for the main index * to refer to a category which is not yet visible in the old snapshot of * the taxonomy. Note that it is indeed fine for the the taxonomy to be opened * after the main index - even a long time after. The reason is that once * a category is added to the taxonomy, it can never be changed or deleted, * so there is no danger that a "too new" taxonomy not being consistent with * an older index. * * @lucene.experimental */ public abstract class TaxonomyReader implements Closeable { /** An iterator over a category's children. */ public static class ChildrenIterator { private final int[] siblings; private int child; ChildrenIterator(int child, int[] siblings) { this.siblings = siblings; this.child = child; } /** * Return the next child ordinal, or {@link TaxonomyReader#INVALID_ORDINAL} * if no more children. */ public int next() { int res = child; if (child != TaxonomyReader.INVALID_ORDINAL) { child = siblings[child]; } return res; } } /** Sole constructor. */ public TaxonomyReader() { } /** * The root category (the category with the empty path) always has the ordinal * 0, to which we give a name ROOT_ORDINAL. {@link #getOrdinal(FacetLabel)} * of an empty path will always return {@code ROOT_ORDINAL}, and * {@link #getPath(int)} with {@code ROOT_ORDINAL} will return the empty path. */ public final static int ROOT_ORDINAL = 0; /** * Ordinals are always non-negative, so a negative ordinal can be used to * signify an error. Methods here return INVALID_ORDINAL (-1) in this case. */ public final static int INVALID_ORDINAL = -1; /** * If the taxonomy has changed since the provided reader was opened, open and * return a new {@link TaxonomyReader}; else, return {@code null}. The new * reader, if not {@code null}, will be the same type of reader as the one * given to this method. * * <p> * This method is typically far less costly than opening a fully new * {@link TaxonomyReader} as it shares resources with the provided * {@link TaxonomyReader}, when possible. */ public static <T extends TaxonomyReader> T openIfChanged(T oldTaxoReader) throws IOException { @SuppressWarnings("unchecked") final T newTaxoReader = (T) oldTaxoReader.doOpenIfChanged(); assert newTaxoReader != oldTaxoReader; return newTaxoReader; } private volatile boolean closed = false; // set refCount to 1 at start private final AtomicInteger refCount = new AtomicInteger(1); /** * performs the actual task of closing the resources that are used by the * taxonomy reader. */ protected abstract void doClose() throws IOException; /** * Implements the actual opening of a new {@link TaxonomyReader} instance if * the taxonomy has changed. * * @see #openIfChanged(TaxonomyReader) */ protected abstract TaxonomyReader doOpenIfChanged() throws IOException; /** * Throws {@link AlreadyClosedException} if this IndexReader is closed */ protected final void ensureOpen() throws AlreadyClosedException { if (getRefCount() <= 0) { throw new AlreadyClosedException("this TaxonomyReader is closed"); } } @Override public final void close() throws IOException { if (!closed) { synchronized (this) { if (!closed) { decRef(); closed = true; } } } } /** * Expert: decreases the refCount of this TaxonomyReader instance. If the * refCount drops to 0 this taxonomy reader is closed. */ public final void decRef() throws IOException { ensureOpen(); final int rc = refCount.decrementAndGet(); if (rc == 0) { boolean success = false; try { doClose(); closed = true; success = true; } finally { if (!success) { // Put reference back on failure refCount.incrementAndGet(); } } } else if (rc < 0) { throw new IllegalStateException("too many decRef calls: refCount is " + rc + " after decrement"); } } /** * Returns a {@link ParallelTaxonomyArrays} object which can be used to * efficiently traverse the taxonomy tree. */ public abstract ParallelTaxonomyArrays getParallelTaxonomyArrays() throws IOException; /** Returns an iterator over the children of the given ordinal. */ public ChildrenIterator getChildren(final int ordinal) throws IOException { ParallelTaxonomyArrays arrays = getParallelTaxonomyArrays(); int child = ordinal >= 0 ? arrays.children()[ordinal] : INVALID_ORDINAL; return new ChildrenIterator(child, arrays.siblings()); } /** * Retrieve user committed data. * * @see TaxonomyWriter#setLiveCommitData(Iterable) */ public abstract Map<String, String> getCommitUserData() throws IOException; /** * Returns the ordinal of the category given as a path. The ordinal is the * category's serial number, an integer which starts with 0 and grows as more * categories are added (note that once a category is added, it can never be * deleted). * * @return the category's ordinal or {@link #INVALID_ORDINAL} if the category * wasn't foun. */ public abstract int getOrdinal(FacetLabel categoryPath) throws IOException; /** Returns ordinal for the dim + path. */ public int getOrdinal(String dim, String[] path) throws IOException { String[] fullPath = new String[path.length + 1]; fullPath[0] = dim; System.arraycopy(path, 0, fullPath, 1, path.length); return getOrdinal(new FacetLabel(fullPath)); } /** Returns the path name of the category with the given ordinal. */ public abstract FacetLabel getPath(int ordinal) throws IOException; /** Returns the current refCount for this taxonomy reader. */ public final int getRefCount() { return refCount.get(); } /** * Returns the number of categories in the taxonomy. Note that the number of * categories returned is often slightly higher than the number of categories * inserted into the taxonomy; This is because when a category is added to the * taxonomy, its ancestors are also added automatically (including the root, * which always get ordinal 0). */ public abstract int getSize(); /** * Expert: increments the refCount of this TaxonomyReader instance. RefCounts * can be used to determine when a taxonomy reader can be closed safely, i.e. * as soon as there are no more references. Be sure to always call a * corresponding decRef(), in a finally clause; otherwise the reader may never * be closed. */ public final void incRef() { ensureOpen(); refCount.incrementAndGet(); } /** Expert: increments the refCount of this TaxonomyReader * instance only if it has not been closed yet. Returns * true on success. */ public final boolean tryIncRef() { int count; while ((count = refCount.get()) > 0) { if (refCount.compareAndSet(count, count + 1)) { return true; } } return false; } }