CompassGps.java

/*
 * Copyright 2004-2009 the original author or authors.
 * 
 * Licensed 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.compass.gps;

/**
 * <code>CompassGps</code> is responsible for managing
 * {@link org.compass.gps.CompassGpsDevice}s. It can hold one or more
 * devices, and manage their lifecycle. It is also resposible for creating an
 * abstraction between devices and their repectice <code>Compass</code>
 * instances, as part of the internal contract between
 * <code>CompassGps</code> and its devices and should not be used by a
 * non-device code (see
 * {@link org.compass.gps.spi.CompassGpsInterfaceDevice}).
 * 
 * @author kimchy
 */
public interface CompassGps {

    /**
     * Adds a {@link CompassGpsDevice} to be managed.
     *
     * @param gpsDevice
     */
    void addGpsDevice(CompassGpsDevice gpsDevice);

    /**
     * Sets a list of {@link CompassGpsDevice}s that will be managed.
     *
     * @param devices
     */
    void setGpsDevices(CompassGpsDevice[] devices);

    /**
     * Start <code>CompassGps</code> (also starts all the devices).
     * 
     * @throws CompassGpsException
     */
    void start() throws CompassGpsException;

    /**
     * Stops <code>CompassGps</code> (also starts all the devices).
     * 
     * @throws CompassGpsException
     */
    void stop() throws CompassGpsException;

    /**
     * Return <code>true</code> is started.
     */
    boolean isRunning();

    /**
     * Retuns <code>true</code> if the devide performs the index operaiton.
     */
    boolean isPerformingIndexOperation();

    /**
     * Indexes all the different devices (by calling their respective
     * <code>index()</code> operation.
     *
     * <p>Similar to calling the {@link #index(IndexPlan)} with a new
     * instance of {@link DefaultIndexPlan} (and nothing else set).
     * 
     * @throws CompassGpsException
     */
    void index() throws CompassGpsException, IllegalStateException;

    /**
     * Index just the given types.
     */
    void index(Class ... types) throws CompassGpsException, IllegalStateException;

    /**
     * Index just the aliases.
     */
    void index(String ... aliases) throws CompassGpsException, IllegalStateException;

    /**
     * Indexes all the different devices based on the given index plan. The index
     * plan, by default, supports constraining the indexing process to specific
     * classes/aliases/sub indexes.
     */
    void index(IndexPlan indexPlan) throws CompassGpsException, IllegalStateException;
}