root/trunk/components/server/src/ome/services/fulltext/BridgeHelper.java

/*
 *   $Id$
 *
 *   Copyright 2008 Glencoe Software, Inc. All rights reserved.
 *   Use is subject to license terms supplied in LICENSE.txt
 */

package ome.services.fulltext;

import java.io.File;
import java.io.Reader;
import java.io.StringReader;
import java.util.Collections;
import java.util.List;
import java.util.Map;

import ome.conditions.ApiUsageException;
import ome.io.nio.OriginalFilesService;
import ome.model.IObject;
import ome.model.core.OriginalFile;
import ome.services.messages.RegisterServiceCleanupMessage;
import ome.services.messages.ReindexMessage;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.lucene.document.Document;
import org.apache.lucene.document.Field;
import org.apache.lucene.document.Field.Store;
import org.hibernate.search.bridge.FieldBridge;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.context.ApplicationEventPublisherAware;

/**
 * Base class for building custom {@link FieldBridge} implementations.
 * 
 * To force handling of null values, the
 * {@link #add(Document, String, String, Store, org.apache.lucene.document.Field.Index, Float)}
 * methods throw {@link NullValueException} which can convert itself to a
 * {@link RuntimeException} via {@link NullValueException#convert(Object)} if
 * that is the simplest course of action. Alternatively, you could re-add the
 * value with a null-token like "null".
 * 
 * @author Josh Moore, josh at glencoesoftware.com
 * @since 3.0-Beta3
 */
public abstract class BridgeHelper implements FieldBridge,
        ApplicationEventPublisherAware {

    /**
     * Name of the {@link Field} which contains the union of all fields. This is
     * also the default search field, so users need not append the value to
     * search the full index. A field name need only be added to a search to
     * eliminate other fields.
     * 
     * @DEV.TODO add to constants
     */
    public final static String COMBINED = "combined_fields";

    private final Log log = LogFactory.getLog(getClass());

    protected ApplicationEventPublisher publisher;

    public final Log logger() {
        return log;
    }

    public void setApplicationEventPublisher(ApplicationEventPublisher publisher) {
        this.publisher = publisher;
    }

    /**
     * Method to be implemented by all {@link FieldBridge bridges}. The "value"
     * argument is an active Hibernate object, and so the full graph can be
     * walked.
     */
    public abstract void set(final String name, final Object value,
            final Document document, final Field.Store store2,
            final Field.Index index, final Float boost);

    /**
     * Helper method which takes the parameters from the
     * {@link #set(String, Object, Document, Store, org.apache.lucene.document.Field.Index, Float)}
     * method (possibly modified) as well as the parsed {@link String} value
     * which should be added to the index, and adds two fields. One with the
     * given field name and another to the {@link #COMBINED} field which is the
     * default search provided to users. In addition to storing the value as is,
     * another {@link Field} will be added for both the named and
     * {@link #COMBINED} cases using a {@link StringReader} to allow Lucene to
     * tokenize the {@link String}.
     * 
     * @param d
     *            Document as passed to the set method. Do not modify.
     * @param field
     *            Field name which probably <em/>should</em> be modified. If
     *            this value is null, then the "value" will only be added to the
     *            {@link #COMBINED} field.
     * @param value
     *            Value which has been parsed out for this field. Should
     *            <em/>not</em> be null. If you need to store a null value in
     *            the index, use a null token like "null".
     * @param store
     *            Whether or not to store the string value in the index. Note:
     *            no values are stored in the {@link #COMBINED} field to prevent
     *            duplication.
     * @param index
     *            Whether or not to make the string searchable.
     * @param boost
     *            Positive float which increases or decreases search importance
     *            for a field. Default is 1.0.
     */
    protected void add(Document d, String field, String value,
            Field.Store store, Field.Index index, Float boost) {

        if (value == null) {
            throw new RuntimeException(
                    "Value for indexing cannot be null. Use a null token instead.");
        }

        // If the field == null, then we ignore it, to allow easy addition
        // of Fields as COMBINED
        if (field != null) {
            final Field named_field = new Field(field, value, store, index);
            if (boost != null) {
                named_field.setBoost(boost);
            }
            d.add(named_field);
            final Field named_parsed_field = new Field(field, new StringReader(
                    value));
            d.add(named_parsed_field);
        }

        // Never storing in combined fields, since it's duplicated
        final Field combined_field = new Field(COMBINED, value, Store.NO, index);
        if (boost != null) {
            combined_field.setBoost(boost);
        }
        d.add(combined_field);
        final Field combined_parsed_field = new Field(COMBINED,
                new StringReader(value));
        d.add(combined_parsed_field);
    }

    /**
     * Second helper method used when parsing files. The {@link OriginalFile}
     * will be passed to {@link #parse(OriginalFile, OriginalFilesService, Map)}
     * to generate {@link Reader} instances, which will be read until they
     * signal an end, however it is not the responsibility of this instance to
     * close the Readers since this happens asynchronously.
     * 
     * The contents of the file will be parsed both to {@link #COMBINED} and
     * "file.contents".
     * 
     * @param d
     *            {@link Document} as passed to set. Do not modify.
     * @params name String to be used as the name of the field. If null, then
     *         the contens will only be added to the {@link #COMBINED}
     *         {@link Field}.
     * @param file
     *            Non-null, possibly unloaded {@link OriginalFile} which is used
     *            to look up the file on disk.
     * @param files
     *            {@link OriginalFileServer} which knows how to find where this
     *            {@link OriginalFile} is stored on disk.
     * @param parsers
     *            {@link Map} of {@link FileParser} instances to be used based
     *            on the {@link Format} of the {@link OriginalFile}
     * @param boost
     *            Positive float which increases or decreases search importance
     *            for a field. Default is 1.0.
     */
    protected void addContents(final Document d, final String name,
            final OriginalFile file, final OriginalFilesService files,
            final Map<String, FileParser> parsers, final Float boost) {

        if (file == null) {
            throw new RuntimeException(
                    "File cannot be null. Either do not attempt to add "
                            + "anything for this field, or use a null token like "
                            + "\"null\" instead.");
        }

        Field f;
        if (name != null) {
            for (Reader parsed : parse(file, files, parsers)) {
                f = new Field(name, parsed);
                if (boost != null) {
                    f.setBoost(boost);
                }
                d.add(f);
            }
        }

        for (Reader parsed : parse(file, files, parsers)) {
            f = new Field(COMBINED, parsed);
            if (boost != null) {
                f.setBoost(boost);
            }
            d.add(f);
        }

    }

    /**
     * Publishes a {@link ReindexMessage} which will get processed
     * asynchronously.
     */
    protected <T extends IObject> void reindex(T object) {
        reindexAll(Collections.singletonList(object));
    }

    /**
     * Publishes a {@link ReindexMessage} which will get processed
     * asynchronously.
     */
    protected <T extends IObject> void reindexAll(List<T> list) {
        if (publisher == null) {
            throw new ApiUsageException(
                    "Bridge is not configured for sending messages.");
        }
        for (T object : list) {
            if (object == null || object.getId() == null) {
                throw new ApiUsageException("Object cannot be null");
            }
        }
        final ReindexMessage<T> rm = new ReindexMessage<T>(this, list);
        publisher.publishEvent(rm);
    }

    /**
     * Attempts to parse the given {@link OriginalFile}. If any of the
     * necessary components is null, then it will return an empty, but not null
     * {@link Iterable}. Also looks for the catch all parser under "*"
     * 
     * @param file
     *            Can be null.
     * @return will not be null.
     */
    protected Iterable<Reader> parse(final OriginalFile file,
            final OriginalFilesService files,
            final Map<String, FileParser> parsers) {
        if (files != null && parsers != null) {
            if (file != null && file.getFormat() != null) {
                String path = files.getFilesPath(file.getId());
                String format = file.getFormat().getValue();
                FileParser parser = parsers.get(format);
                if (parser != null) {
                    return parser.parse(new File(path));
                } else {
                    parser = parsers.get("*");
                    if (parser != null) {
                        return parser.parse(new File(path));
                    }
                }
            }
        }
        return FileParser.EMPTY;
    }
}