syncsource.java

SyncML的java实现类库 funambol公司发布的

/*
 * Copyright (C) 2006-2007 Funambol
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 */

package com.funambol.syncml.spds;

import com.funambol.syncml.protocol.SyncFilter;

/**
 * A <i>SyncSource</i> is responsible for storing and retrieving <i>SyncItem</i>
 * objects from/to an external data source.
 * Note that the <i>SyncSource</i> interface makes no assumptions about the
 * underlying data source or about how data are formatted: each concrete
 * implementation will use its specific storage and format.
 * <p>
 * A <i>SyncSource</i> is not used directly by the host application, instead its
 * methods are called by the synchronization engine during modifications analysis.
 * <p>
 * The SyncSource methods are designed to perform an efficient synchronization
 * process, letting the source selecting the changed items instead of doing more
 * complex field by field comparison. It is responsibility of the source
 * developer to make sure that the <i>getNextNew/Updated/DeletedItem()</i>
 * methods return the correct values.
 * <p>
 * The configuration information required to set up a SyncSource is stored in
 * the class <i>SourceConfig</i> , used by the BaseSyncSource class.
 */
public interface SyncSource {
    
    //------------------------------------------------------------ Attributes
    
    public static final String ENCODING_NONE = "none" ;
    public static final String ENCODING_B64  = "b64"  ;

    //--------------------------------------------------------------- Methods

    /**
     * Returns the name of the source
     *
     * @return the name of the source
     */
    public String getName();

    /**
     * Returns the source URI
     *
     * @return the absolute URI of the source
     */
    public String getSourceUri();

    /**
     * Returns the type of the source.
     * The types are defined as mime-types, for instance * text/x-vcard).
     * @return the type of the source
     */
    public String getType();

    /**
     * Returns the encoding of the source.
     * The encoding can be 'b64' or 'none' only. The standard defines
     * also 'des' and '3des' but they are not implemented in this version
     * of the APIs.
     *
     * @return the encoding of the source
     */
    public String getEncoding();

    /**
     * Return the preferred sync mode of the source.
     * The preferred sync mode is the one that the SyncManager sends
     * to the server in the initialization phase. The server can respond
     * with a different alert code, to force, for instance, a slow.
     *
     * @return the preferred sync mode for this source
     */
    public int getSyncMode() ;

    /**
     * Return the current filter for this SyncSource
     *
     */
    public SyncFilter getFilter();

    /**
     * Set a new filter for this SyncSource
     *
     */
    public void setFilter(SyncFilter filter);

    /**
     * Add a new SyncItem to this source backend.
     * The item key after a successful add must contain the local UID,
     * that is used by the engine to send the mappings to the server.
     * The source must then change the item key accordingly before return.
     *
     * @param item the SyncItem to add, with the GUID sent by the server.
     *             The source is resposible to set it to the LUID before
     *             returning a successful status code.
     *
     * @return the status code of the operation. It will be returned to
     *         the server in the response for this item.
     *
     * @throws SyncException if an unrecoverable error occur, to stop the sync
     */
    public int addItem(SyncItem item) throws SyncException;
    
    /**
     * Update a given SyncItem stored in the source backend.
     *
     * @param item the SyncItem to update. The key of the item is already
     *             the LUID.
     *
     * @return the status code of the operation. It will be returned to
     *         the server in the response for this item.
     *
     * @throws SyncException if an unrecoverable error occur, to stop the sync
     */
    public int updateItem(SyncItem item) throws SyncException;
    
    /**
     * Delete a SyncItem stored in the source backend.
     *
     * @param key The key of the item to delete.
     *
     * @return the status code of the operation. It will be returned to
     *         the server in the response for this item.
     *
     * @throws SyncException if an unrecoverable error occur, to stop the sync
     */
    public int deleteItem(String key) throws SyncException;
    
    /**
     * Returns the next item of the store (for slow sync).<p>
     * The implementation of this method must iterate on all the 
     * items of the source, starting from the first after a beginSync()
     * call and returning <code>null</code> when no more items
     * are available.
     */
    public SyncItem getNextItem() throws SyncException;
    
    /**
     * Returns the first/next new item of the store.<p>
     * The implementation of this method must iterate on the items of the
     * source not yet sent to the server, starting from the first one after a
     * beginSync() call and returning <code>null</code> when no more items are
     * available.
     *
     * @return the first new item, in a SyncItem object, or null if
     *         no new items are present.
     */
    public SyncItem getNextNewItem() throws SyncException;
    
    /**
     * Returns the first/next updated item of the store
     * (changed from the last sync)
     *
     * @return the first updated item, in a SyncItem object, or null if
     *         no updated items are present.
     */
    public SyncItem getNextUpdatedItem() throws SyncException;
    
    /** 
     * Returns a SyncItem containing the key of the first/next
     * deleted item of the store (locally removed after the last sync,
     * but not yet deleted on server)
     *
     * @return the first deleted item, in a SyncItem object, or null if
     *         no deleted items are present.
     */
    public SyncItem getNextDeletedItem() throws SyncException;
    
    /**
     * Tell the SyncSource the status returned by the server 
     * for an Item previously sent.
     *
     * @param key the key of the item
     * @param status the status code received for that item
     *
     * @throws SyncException if the SyncSource wants to stop the sync
     */
    public void setItemStatus(String key, int status) throws SyncException ;

    /**
     * Called by the engine when new data has been received by the server,
     * before processing it.
     *
     * The date is in the format received in the HTTP headers, if available.
     * This enable clients running on devices without timezone support to
     * detect the time and location of the server, and thus the timezone of
     * the client.
     * The size is the total size of the received message, in bytes.
     */
    public void dataReceived(String date, int size);
    
    /**
     * Return the number of changes that the client will send during the
     * session. This method, after the beginSync() call, should return
     * the number of items to be sent to the server.
     *
     * This is a read-only value for the Syncmanager.
     *
     * @return number of items to sent, or -1 if unknown
     */
    public int getClientItemsNumber();

    /**
     * Retiurn the number of changes that the server will send during the
     * session.
     * The value is set by the engine after the Sync tag is sent by the
     * server, with the value of the NumberOfchanges tag or -1 if not present.
     *
     * @return number of changes from the server, or -1 if not announced.
     */
    public int getServerItemsNumber();

    /**
     * Set the number of changes that the server will send during the
     * session. This method is called by the engine to notify the Source
     * of the number of changes announced by the server. If the server
     * does not announce the number of changes, the engine will call
     * this method with parameter -1.
     *
     * @param number of changes from the server, or -1 if not announced.
     */
    public void setServerItemsNumber(int number);

    /** 
     * Return the Last Anchor for this source
     */
    public long getLastAnchor();
    
    /** 
     * Set the value of the Last Anchor for this source
     */
    public void setLastAnchor(long time);
    
    /** 
     * Return the Next Anchor for this source
     */
    public long getNextAnchor();
    
    /** 
     * Set the value of the Next Anchor for this source
     */
    public void setNextAnchor(long time);

    /**
     * Called after SyncManager preparation and initialization just before start
     * the synchronization of the SyncSource.
     * The implementation must reset the all/new/upd/del item lists when this
     * method is called by the sync engine.
     *
     * @param syncMode the synchronization type: one of the values in
     *                 sync4j.framework.core.AlertCode
     *
     * @throws SyncException in case of error. This will stop the sync process
     */
    public void beginSync(int syncMode) throws SyncException;
    

    /**
     * Called just before committing the synchronization process by the
     * SyncManager. The SyncSource can stop the commit phase raising an
     * exception here.
     *
     * @throws SyncException in case of error, to stop the commit.
     */
    public void endSync() throws SyncException;


}