001: /*
002: * Copyright 2004-2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.compass.gps;
018:
019: /**
020: * A Compass Gps Device is responsible for interacting with a data source and
021: * reflecting it in a compass index. A data source can be a file system, or a
022: * database through the use of ORM tool (like hibernate).
023: *
024: * <p>A device should be able to provide the ability to index the data source,
025: * which usually means iterating through the device data and indexing it. It
026: * might also provide "real time" monitoring of changes in the device, and
027: * applying them to the index as well.
028: *
029: * <p>A CompassGpsDevice can not operate as a standalone, and must be a part of a
030: * {@link org.compass.gps.CompassGps} instance (even if we have only one
031: * device), since the device requires the Compass and the Batch Compass
032: * instances in order to apply the changes to the index.
033: *
034: * <p>The device has a name associated with it, and the name must be unique among
035: * all the devices within a single CompassGps instance.
036: *
037: * @author kimchy
038: */
039: public interface CompassGpsDevice {
040:
041: /**
042: * Returns the name associated with the device.
043: *
044: * @return The name of the device.
045: */
046: String getName();
047:
048: /**
049: * Sets the name associated with the device.
050: */
051: void setName(String name);
052:
053: /**
054: * Sets the CompassGps that manages the device. Optional, since if the
055: * device is added to a CompassGps instance, it will be done automatically.
056: */
057: void injectGps(CompassGps compassGps);
058:
059: /**
060: * Returns the CompassGps that manages the device.
061: *
062: * @return compassGps
063: */
064: CompassGps getGps();
065:
066: /**
067: * Starts the device. Optional, since it is preferable to manage the all the
068: * devices through the CompassGps API.
069: *
070: * @throws CompassGpsException
071: */
072: void start() throws CompassGpsException;
073:
074: /**
075: * Stops the device. Optional, since it is preferable to manage the all the
076: * devices through the CompassGps API.
077: *
078: * @throws CompassGpsException
079: */
080: void stop() throws CompassGpsException;
081:
082: /**
083: * Returns if the device is running.
084: *
085: * @return <code>true</code> if theh device is running
086: */
087: boolean isRunning();
088:
089: /**
090: * Index the device. Optional, since it is preferable to manage the all the
091: * devices through the CompassGps API.
092: *
093: * @throws CompassGpsException
094: * @throws IllegalStateException
095: */
096: void index() throws CompassGpsException, IllegalStateException;
097:
098: /**
099: * Retuns <code>true</code> if the devide performs the index operaiton.
100: */
101: public boolean isPerformingIndexOperation();
102:
103: /**
104: * Returns <code>true</code> if the device is required to perform mirror operation.
105: */
106: boolean shouldMirrorDataChanges();
107: }
|