content: /*
   * CDDL HEADER START
   *
   * The contents of this file are subject to the terms of the Common Development
   * and Distribution License (the "License").
   * You may not use this file except in compliance with the License.
   *
   * You can obtain a copy of the license at
   * src/com/vodafone360/people/VODAFONE.LICENSE.txt or
   * http://github.com/360/360-Engine-for-Android
   * See the License for the specific language governing permissions and
   * limitations under the License.
   *
   * When distributing Covered Code, include this CDDL HEADER in each file and
   * include the License file at src/com/vodafone360/people/VODAFONE.LICENSE.txt.
   * If applicable, add the following below this CDDL HEADER, with the fields
   * enclosed by brackets "[]" replaced with your own identifying information:
   * Portions Copyright [yyyy] [name of copyright owner]
   *
   * CDDL HEADER END
   *
   * Copyright 2010 Vodafone Sales & Services Ltd.  All rights reserved.
   * Use is subject to license terms.
   */
  
  package com.vodafone360.people.engine.contactsync;
  
  import java.security.InvalidParameterException;
  
  import com.vodafone360.people.database.DatabaseHelper;
  import com.vodafone360.people.engine.BaseEngine;
  import com.vodafone360.people.service.ServiceStatus;
  import com.vodafone360.people.service.io.ResponseQueue.DecodedResponse;
  
  /**
   * Base-class for processor handling for the various stages of Contact sync.
   */
  public abstract class BaseSyncProcessor {
      /**
       * Provides useful callback methods in the contact sync engine
       */
      protected IContactSyncCallback mCallback;
  
      /**
       * String used by processors to compile extra information when a contact
       * sync isn't successful. Currently used to list contacts which the server
       * does not accept during the sync.
       */
      protected String mFailureList;
  
      /**
       * Provides processors with access to the people database.
       */
      protected DatabaseHelper mDb;
  
      /**
       * Base constructor.
       * 
       * @param callback Provides access to the contact sync engine
       * @param db The database helper reference
       */
      protected BaseSyncProcessor(IContactSyncCallback callback, DatabaseHelper db) {
          mCallback = callback;
          mDb = db;
      }
  
      /**
       * Start the processor. Once started the processors is in the active state
       * until either it is cancelled by engine, or the processor completes the
       * sync (see {@link #complete(ServiceStatus)}).
       */
      public void start() {
          mFailureList = "";
          doStart();
      }
  
      /**
       * Cancel processor
       */
      protected void cancel() {
          doCancel();
          complete(ServiceStatus.USER_CANCELLED);
      }
  
      /**
       * Implemented by all contact sync processors to initiate the sync. Once
       * called, the processor needs to call the
       * {@link IContactSyncCallback#onProcessorComplete(ServiceStatus, String, Object)}
       * method when the sync is finished (the usual way to do this is by calling
       * {@link #complete(ServiceStatus)}).
       */
      protected abstract void doStart();
  
      /**
       * Can be called anytime when the processor is active, to cancel the sync.
       * Should not complete the sync here because the above method
       * {@link #cancel()} will take care of this.
       */
      protected abstract void doCancel();
  
      /**
       * Can be overriden by processors which are interested in timeout events. A
       * processor will only receive timeout events while it is active.
       */
      public void onTimeoutEvent() {
      }
  
      /**
       * Called when a comms response is received from the server. This may be a
       * response from a request issued by the processor or a push message.
       * 
       * @param resp The response data
       */
      public abstract void processCommsResponse(DecodedResponse resp);
  
      /**
       * Helper method to complete the processor.
       * 
       * @param status The result of the sync
       */
      protected void complete(ServiceStatus status) {
          mCallback.onProcessorComplete(status, mFailureList, null);
      }
  
      /**
       * Provides access to the contact sync engine object. This is normally only
       * used for processor to issue comms requests.
       * 
       * @return The contact sync engine
       */
      protected BaseEngine getEngine() {
          return mCallback.getEngine();
      }
  
      /**
       * Called by processors when they make changes to the people database. This
       * is implemented outside the database framework to ensure UI updates happen
       * more efficiently during a contact sync.
       */
      protected void markDbChanged() {
          mCallback.onDatabaseChanged();
      }
  
      /**
       * Helper function that can be used by processors to set a timeout. The
       * {@link #onTimeoutEvent()} will be called once the timeout completes.
       * 
       * @note Only a single timeout is allowed at any time, so setting a timeout
       *       will cancel any previous pending timeout.
       * @param timeout The timeout value in milliseconds.
       */
      protected void setTimeout(long timeout) {
          mCallback.setTimeout(timeout);
      }
      
      /**
       * Used by processors to provide an indication of their current progress.
       * 
       * @param SyncStatus Status of the processor, must not be NULL.
       * @throws InvalidParameterException when SyncStatus is NULL.
       */
      protected void setSyncStatus(SyncStatus syncStatus) {
          mCallback.setSyncStatus(syncStatus);
      }
  
      /**
       * Processors can call this method when they issue a comms requests. The
       * framework will then only notify the processor when a response is received
       * which matches the request ID.
       * 
       * @param reqId The request ID returned by the comms framework.
       */
      protected void setReqId(int reqId) {
          if (reqId == -1) {
              complete(ServiceStatus.ERROR_COMMS);
              return;
          }
          mCallback.setActiveRequestId(reqId);
      }
  
      /**
       * Processors may override this function is they have any additional cleanup
       * to do when the processor has finished. Similiar to finalize except it is
       * always called immediately the processor goes inactive.
       */
      public void onComplete() {
  
      }
  }
  