src/com/android/messaging/datamodel/action/Action.java - platform/packages/apps/Messaging - Git at Google

 /*
  * Copyright (C) 2015 The Android Open Source Project
  *
  * 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 com.android.messaging.datamodel.action;

 import android.os.Bundle;
 import android.os.Parcel;
 import android.os.Parcelable;
 import android.text.TextUtils;

 import com.android.messaging.datamodel.DataModel;
 import com.android.messaging.datamodel.DataModelException;
 import com.android.messaging.datamodel.action.ActionMonitor.ActionCompletedListener;
 import com.android.messaging.datamodel.action.ActionMonitor.ActionExecutedListener;
 import com.android.messaging.util.LogUtil;

 import java.util.LinkedList;
 import java.util.List;

 /**
  * Base class for operations that perform application business logic off the main UI thread while
  * holding a wake lock.
  * .
  * Note all derived classes need to provide real implementation of Parcelable (this is abstract)
  */
 public abstract class Action implements Parcelable {
     private static final String TAG = LogUtil.BUGLE_DATAMODEL_TAG;

     // Members holding the parameters common to all actions - no action state
     public final String actionKey;

     // If derived classes keep their data in actionParameters then parcelable is trivial
     protected Bundle actionParameters;

     // This does not get written to the parcel
     private final List<Action> mBackgroundActions = new LinkedList<Action>();

     /**
      * Process the action locally - runs on action service thread.
      * TODO: Currently, there is no way for this method to indicate failure
      * @return result to be passed in to {@link ActionExecutedListener#onActionExecuted}. It is
      *         also the result passed in to {@link ActionCompletedListener#onActionSucceeded} if
      *         there is no background work.
      */
     protected Object executeAction() {
         return null;
     }

     /**
      * Queues up background work ie. {@link #doBackgroundWork} will be called on the
      * background worker thread.
      */
     protected void requestBackgroundWork() {
         mBackgroundActions.add(this);
     }

     /**
      * Queues up background actions for background processing after the current action has
      * completed its processing ({@link #executeAction}, {@link processBackgroundCompletion}
      * or {@link #processBackgroundFailure}) on the Action thread.
      * @param backgroundAction
      */
     protected void requestBackgroundWork(final Action backgroundAction) {
         mBackgroundActions.add(backgroundAction);
     }

     /**
      * Return flag indicating if any actions have been queued
      */
     public boolean hasBackgroundActions() {
         return !mBackgroundActions.isEmpty();
     }

     /**
      * Send queued actions to the background worker provided
      */
     public void sendBackgroundActions(final BackgroundWorker worker) {
         worker.queueBackgroundWork(mBackgroundActions);
         mBackgroundActions.clear();
     }

     /**
      * Do work in a long running background worker thread.
      * {@link #requestBackgroundWork} needs to be called for this method to
      * be called. {@link #processBackgroundFailure} will be called on the Action service thread
      * if this method throws {@link DataModelException}.
      * @return response that is to be passed to {@link #processBackgroundResponse}
      */
     protected Bundle doBackgroundWork() throws DataModelException {
         return null;
     }

     /**
      * Process the success response from the background worker. Runs on action service thread.
      * @param response the response returned by {@link #doBackgroundWork}
      * @return result to be passed in to {@link ActionCompletedListener#onActionSucceeded}
      */
     protected Object processBackgroundResponse(final Bundle response) {
         return null;
     }

     /**
      * Called in case of failures when sending background actions. Runs on action service thread
      * @return result to be passed in to {@link ActionCompletedListener#onActionFailed}
      */
     protected Object processBackgroundFailure() {
         return null;
     }

     /**
      * Constructor
      */
     protected Action(final String key) {
         this.actionKey = key;
         this.actionParameters = new Bundle();
     }

     /**
      * Constructor
      */
     protected Action() {
         this.actionKey = generateUniqueActionKey(getClass().getSimpleName());
         this.actionParameters = new Bundle();
     }

     /**
      * Queue an action and monitor for processing by the ActionService via the factory helper
      */
     protected void start(final ActionMonitor monitor) {
         ActionMonitor.registerActionMonitor(this.actionKey, monitor);
         DataModel.startActionService(this);
     }

     /**
      * Queue an action for processing by the ActionService via the factory helper
      */
     public void start() {
         DataModel.startActionService(this);
     }

     /**
      * Queue an action for delayed processing by the ActionService via the factory helper
      */
     public void schedule(final int requestCode, final long delayMs) {
         DataModel.scheduleAction(this, requestCode, delayMs);
     }

     /**
      * Called when action queues ActionService intent
      */
     protected final void markStart() {
         ActionMonitor.setState(this, ActionMonitor.STATE_CREATED,
                 ActionMonitor.STATE_QUEUED);
     }

     /**
      * Mark the beginning of local action execution
      */
     protected final void markBeginExecute() {
         ActionMonitor.setState(this, ActionMonitor.STATE_QUEUED,
                 ActionMonitor.STATE_EXECUTING);
     }

     /**
      * Mark the end of local action execution - either completes the action or queues
      * background actions
      */
     protected final void markEndExecute(final Object result) {
         final boolean hasBackgroundActions = hasBackgroundActions();
         ActionMonitor.setExecutedState(this, ActionMonitor.STATE_EXECUTING,
                 hasBackgroundActions, result);
         if (!hasBackgroundActions) {
             ActionMonitor.setCompleteState(this, ActionMonitor.STATE_EXECUTING,
                     result, true);
         }
     }

     /**
      * Update action state to indicate that the background worker is starting
      */
     protected final void markBackgroundWorkStarting() {
         ActionMonitor.setState(this,
                 ActionMonitor.STATE_BACKGROUND_ACTIONS_QUEUED,
                 ActionMonitor.STATE_EXECUTING_BACKGROUND_ACTION);
     }

     /**
      * Update action state to indicate that the background worker has posted its response
      * (or failure) to the Action service
      */
     protected final void markBackgroundCompletionQueued() {
         ActionMonitor.setState(this,
                 ActionMonitor.STATE_EXECUTING_BACKGROUND_ACTION,
                 ActionMonitor.STATE_BACKGROUND_COMPLETION_QUEUED);
     }

     /**
      * Update action state to indicate the background action failed but is being re-queued for retry
      */
     protected final void markBackgroundWorkQueued() {
         ActionMonitor.setState(this,
                 ActionMonitor.STATE_EXECUTING_BACKGROUND_ACTION,
                 ActionMonitor.STATE_BACKGROUND_ACTIONS_QUEUED);
     }

     /**
      * Called by ActionService to process a response from the background worker
      * @param response the response returned by {@link #doBackgroundWork}
      */
     protected final void processBackgroundWorkResponse(final Bundle response) {
         ActionMonitor.setState(this,
                 ActionMonitor.STATE_BACKGROUND_COMPLETION_QUEUED,
                 ActionMonitor.STATE_PROCESSING_BACKGROUND_RESPONSE);
         final Object result = processBackgroundResponse(response);
         ActionMonitor.setCompleteState(this,
                 ActionMonitor.STATE_PROCESSING_BACKGROUND_RESPONSE, result, true);
     }

     /**
      * Called by ActionService when a background action fails
      */
     protected final void processBackgroundWorkFailure() {
         final Object result = processBackgroundFailure();
         ActionMonitor.setCompleteState(this, ActionMonitor.STATE_UNDEFINED,
                 result, false);
     }

     private static final Object sLock = new Object();
     private static long sActionIdx = System.currentTimeMillis() * 1000;

     /**
      * Helper method to generate a unique operation index
      */
     protected static long getActionIdx() {
         long idx = 0;
         synchronized (sLock) {
             idx = ++sActionIdx;
         }
         return idx;
     }

     /**
      * This helper can be used to generate a unique key used to identify an action.
      * @param baseKey - key generated to identify the action parameters
      * @return - composite key generated by appending unique index
      */
     protected static String generateUniqueActionKey(final String baseKey) {
         final StringBuilder key = new StringBuilder();
         if (!TextUtils.isEmpty(baseKey)) {
             key.append(baseKey);
         }
         key.append(":");
         key.append(getActionIdx());
         return key.toString();
     }

     /**
      * Most derived classes use this base implementation (unless they include files handles)
      */
     @Override
     public int describeContents() {
         return 0;
     }

     /**
      * Derived classes need to implement writeToParcel (but typically should call this method
      * to parcel Action member variables before they parcel their member variables).
      */
     public void writeActionToParcel(final Parcel parcel, final int flags) {
         parcel.writeString(this.actionKey);
         parcel.writeBundle(this.actionParameters);
     }

     /**
      * Helper for derived classes to implement parcelable
      */
     public Action(final Parcel in) {
         this.actionKey = in.readString();
         // Note: Need to set classloader to ensure we can un-parcel classes from this package
         this.actionParameters = in.readBundle(Action.class.getClassLoader());
     }
 }
	/*
	* Copyright (C) 2015 The Android Open Source Project
	*
	* 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 com.android.messaging.datamodel.action;

	import android.os.Bundle;
	import android.os.Parcel;
	import android.os.Parcelable;
	import android.text.TextUtils;

	import com.android.messaging.datamodel.DataModel;
	import com.android.messaging.datamodel.DataModelException;
	import com.android.messaging.datamodel.action.ActionMonitor.ActionCompletedListener;
	import com.android.messaging.datamodel.action.ActionMonitor.ActionExecutedListener;
	import com.android.messaging.util.LogUtil;

	import java.util.LinkedList;
	import java.util.List;

	/**
	* Base class for operations that perform application business logic off the main UI thread while
	* holding a wake lock.
	* .
	* Note all derived classes need to provide real implementation of Parcelable (this is abstract)
	*/
	public abstract class Action implements Parcelable {
	private static final String TAG = LogUtil.BUGLE_DATAMODEL_TAG;

	// Members holding the parameters common to all actions - no action state
	public final String actionKey;

	// If derived classes keep their data in actionParameters then parcelable is trivial
	protected Bundle actionParameters;

	// This does not get written to the parcel
	private final List<Action> mBackgroundActions = new LinkedList<Action>();

	/**
	* Process the action locally - runs on action service thread.
	* TODO: Currently, there is no way for this method to indicate failure
	* @return result to be passed in to {@link ActionExecutedListener#onActionExecuted}. It is
	* also the result passed in to {@link ActionCompletedListener#onActionSucceeded} if
	* there is no background work.
	*/
	protected Object executeAction() {
	return null;
	}

	/**
	* Queues up background work ie. {@link #doBackgroundWork} will be called on the
	* background worker thread.
	*/
	protected void requestBackgroundWork() {
	mBackgroundActions.add(this);
	}

	/**
	* Queues up background actions for background processing after the current action has
	* completed its processing ({@link #executeAction}, {@link processBackgroundCompletion}
	* or {@link #processBackgroundFailure}) on the Action thread.
	* @param backgroundAction
	*/
	protected void requestBackgroundWork(final Action backgroundAction) {
	mBackgroundActions.add(backgroundAction);
	}

	/**
	* Return flag indicating if any actions have been queued
	*/
	public boolean hasBackgroundActions() {
	return !mBackgroundActions.isEmpty();
	}

	/**
	* Send queued actions to the background worker provided
	*/
	public void sendBackgroundActions(final BackgroundWorker worker) {
	worker.queueBackgroundWork(mBackgroundActions);
	mBackgroundActions.clear();
	}

	/**
	* Do work in a long running background worker thread.
	* {@link #requestBackgroundWork} needs to be called for this method to
	* be called. {@link #processBackgroundFailure} will be called on the Action service thread
	* if this method throws {@link DataModelException}.
	* @return response that is to be passed to {@link #processBackgroundResponse}
	*/
	protected Bundle doBackgroundWork() throws DataModelException {
	return null;
	}

	/**
	* Process the success response from the background worker. Runs on action service thread.
	* @param response the response returned by {@link #doBackgroundWork}
	* @return result to be passed in to {@link ActionCompletedListener#onActionSucceeded}
	*/
	protected Object processBackgroundResponse(final Bundle response) {
	return null;
	}

	/**
	* Called in case of failures when sending background actions. Runs on action service thread
	* @return result to be passed in to {@link ActionCompletedListener#onActionFailed}
	*/
	protected Object processBackgroundFailure() {
	return null;
	}

	/**
	* Constructor
	*/
	protected Action(final String key) {
	this.actionKey = key;
	this.actionParameters = new Bundle();
	}

	/**
	* Constructor
	*/
	protected Action() {
	this.actionKey = generateUniqueActionKey(getClass().getSimpleName());
	this.actionParameters = new Bundle();
	}

	/**
	* Queue an action and monitor for processing by the ActionService via the factory helper
	*/
	protected void start(final ActionMonitor monitor) {
	ActionMonitor.registerActionMonitor(this.actionKey, monitor);
	DataModel.startActionService(this);
	}

	/**
	* Queue an action for processing by the ActionService via the factory helper
	*/
	public void start() {
	DataModel.startActionService(this);
	}

	/**
	* Queue an action for delayed processing by the ActionService via the factory helper
	*/
	public void schedule(final int requestCode, final long delayMs) {
	DataModel.scheduleAction(this, requestCode, delayMs);
	}

	/**
	* Called when action queues ActionService intent
	*/
	protected final void markStart() {
	ActionMonitor.setState(this, ActionMonitor.STATE_CREATED,
	ActionMonitor.STATE_QUEUED);
	}

	/**
	* Mark the beginning of local action execution
	*/
	protected final void markBeginExecute() {
	ActionMonitor.setState(this, ActionMonitor.STATE_QUEUED,
	ActionMonitor.STATE_EXECUTING);
	}

	/**
	* Mark the end of local action execution - either completes the action or queues
	* background actions
	*/
	protected final void markEndExecute(final Object result) {
	final boolean hasBackgroundActions = hasBackgroundActions();
	ActionMonitor.setExecutedState(this, ActionMonitor.STATE_EXECUTING,
	hasBackgroundActions, result);
	if (!hasBackgroundActions) {
	ActionMonitor.setCompleteState(this, ActionMonitor.STATE_EXECUTING,
	result, true);
	}
	}

	/**
	* Update action state to indicate that the background worker is starting
	*/
	protected final void markBackgroundWorkStarting() {
	ActionMonitor.setState(this,
	ActionMonitor.STATE_BACKGROUND_ACTIONS_QUEUED,
	ActionMonitor.STATE_EXECUTING_BACKGROUND_ACTION);
	}

	/**
	* Update action state to indicate that the background worker has posted its response
	* (or failure) to the Action service
	*/
	protected final void markBackgroundCompletionQueued() {
	ActionMonitor.setState(this,
	ActionMonitor.STATE_EXECUTING_BACKGROUND_ACTION,
	ActionMonitor.STATE_BACKGROUND_COMPLETION_QUEUED);
	}

	/**
	* Update action state to indicate the background action failed but is being re-queued for retry
	*/
	protected final void markBackgroundWorkQueued() {
	ActionMonitor.setState(this,
	ActionMonitor.STATE_EXECUTING_BACKGROUND_ACTION,
	ActionMonitor.STATE_BACKGROUND_ACTIONS_QUEUED);
	}

	/**
	* Called by ActionService to process a response from the background worker
	* @param response the response returned by {@link #doBackgroundWork}
	*/
	protected final void processBackgroundWorkResponse(final Bundle response) {
	ActionMonitor.setState(this,
	ActionMonitor.STATE_BACKGROUND_COMPLETION_QUEUED,
	ActionMonitor.STATE_PROCESSING_BACKGROUND_RESPONSE);
	final Object result = processBackgroundResponse(response);
	ActionMonitor.setCompleteState(this,
	ActionMonitor.STATE_PROCESSING_BACKGROUND_RESPONSE, result, true);
	}

	/**
	* Called by ActionService when a background action fails
	*/
	protected final void processBackgroundWorkFailure() {
	final Object result = processBackgroundFailure();
	ActionMonitor.setCompleteState(this, ActionMonitor.STATE_UNDEFINED,
	result, false);
	}

	private static final Object sLock = new Object();
	private static long sActionIdx = System.currentTimeMillis() * 1000;

	/**
	* Helper method to generate a unique operation index
	*/
	protected static long getActionIdx() {
	long idx = 0;
	synchronized (sLock) {
	idx = ++sActionIdx;
	}
	return idx;
	}

	/**
	* This helper can be used to generate a unique key used to identify an action.
	* @param baseKey - key generated to identify the action parameters
	* @return - composite key generated by appending unique index
	*/
	protected static String generateUniqueActionKey(final String baseKey) {
	final StringBuilder key = new StringBuilder();
	if (!TextUtils.isEmpty(baseKey)) {
	key.append(baseKey);
	}
	key.append(":");
	key.append(getActionIdx());
	return key.toString();
	}

	/**
	* Most derived classes use this base implementation (unless they include files handles)
	*/
	@Override
	public int describeContents() {
	return 0;
	}

	/**
	* Derived classes need to implement writeToParcel (but typically should call this method
	* to parcel Action member variables before they parcel their member variables).
	*/
	public void writeActionToParcel(final Parcel parcel, final int flags) {
	parcel.writeString(this.actionKey);
	parcel.writeBundle(this.actionParameters);
	}

	/**
	* Helper for derived classes to implement parcelable
	*/
	public Action(final Parcel in) {
	this.actionKey = in.readString();
	// Note: Need to set classloader to ensure we can un-parcel classes from this package
	this.actionParameters = in.readBundle(Action.class.getClassLoader());
	}
	}