xiangmuyi/GTaskSyncService.java

/*
 * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net)
 *
 * 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 net.micode.notes.gtask.remote;

import android.app.Activity;
import android.app.Service;
import android.content.Context;
import android.content.Intent;
import android.os.Bundle;
import android.os.IBinder;

// GTaskSyncService类继承自Service，用于管理GTask相关的同步任务，提供了启动、取消同步任务的功能，并且能在不同状态下（如内存不足等）进行相应处理，同时可以对外广播同步相关的状态信息
public class GTaskSyncService extends Service {

    // 定义一个字符串常量，用于作为区分不同同步操作行为的Intent的Extra字段的键名
    public final static String ACTION_STRING_NAME = "sync_action_type";

    // 定义一个整数常量，表示启动同步任务的操作类型，作为通过Intent传递操作类型时的一个标识值
    public final static int ACTION_START_SYNC = 0;

    // 定义一个整数常量，表示取消同步任务的操作类型
    public final static int ACTION_CANCEL_SYNC = 1;

    // 定义一个整数常量，表示无效的操作类型，可能用于默认情况或者错误处理时的标识
    public final static int ACTION_INVALID = 2;

    // 定义一个字符串常量，作为用于广播GTask同步服务相关信息的Intent的动作（Action）名称，用于区分不同来源的广播
    public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service";

    // 定义一个字符串常量，作为广播Intent中用于表示是否正在同步的Extra字段的键名，用于传递同步状态信息
    public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing";

    // 定义一个字符串常量，作为广播Intent中用于表示同步进度消息的Extra字段的键名，用于传递同步过程中的进度提示等信息
    public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg";

    // 静态变量，用于保存当前正在执行的GTaskASyncTask实例，初始化为null，表示没有正在进行的同步任务
    private static GTaskASyncTask mSyncTask = null;

    // 静态变量，用于保存同步任务的进度消息，初始化为空字符串
    private static String mSyncProgress = "";

    // 私有方法，用于启动同步任务，如果当前没有正在执行的同步任务，则创建一个新的GTaskASyncTask实例并执行它
    private void startSync() {
        // 判断当前是否没有正在执行的同步任务（即mSyncTask为null）
        if (mSyncTask == null) {
            // 创建一个新的GTaskASyncTask实例，传入当前服务的上下文（this表示当前Service实例）以及一个实现了OnCompleteListener接口的匿名内部类对象
            mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
                // 实现OnCompleteListener接口的onComplete方法，当同步任务完成时会被调用
                public void onComplete() {
                    // 将正在执行的同步任务实例置为null，表示同步任务已结束
                    mSyncTask = null;
                    // 发送一个空消息的广播（可能用于通知其他组件同步已完成等情况，具体作用依赖接收广播的组件逻辑）
                    sendBroadcast("");
                    // 停止当前服务自身，因为同步任务已经完成，服务不再需要继续运行
                    stopSelf();
                }
            });
            // 发送一个空消息的广播（可能在任务启动阶段通知其他组件同步即将开始等情况）
            sendBroadcast("");
            // 执行同步任务，启动后台线程开始执行GTask相关的同步操作
            mSyncTask.execute();
        }
    }

    // 私有方法，用于取消正在执行的同步任务，如果当前有正在执行的同步任务，则调用其cancelSync方法进行取消操作
    private void cancelSync() {
        if (mSyncTask!= null) {
            mSyncTask.cancelSync();
        }
    }

    // 重写Service的onCreate方法，在服务创建时被调用，这里将正在执行的同步任务实例置为null，进行初始化操作
    @Override
    public void onCreate() {
        mSyncTask = null;
    }

    // 重写Service的onStartCommand方法，当服务接收到通过startService方法启动的Intent时被调用，根据传入Intent中的操作类型执行相应的同步操作逻辑
    @Override
    public int onStartCommand(Intent intent, int flags, int startId) {
        // 获取传入Intent中的额外数据（以Bundle形式存储）
        Bundle bundle = intent.getExtras();
        // 判断Bundle是否不为null且包含了用于区分操作类型的键（ACTION_STRING_NAME）
        if (bundle!= null && bundle.containsKey(ACTION_STRING_NAME)) {
            // 根据操作类型的值进行不同的处理，通过获取操作类型整数值（默认值为ACTION_INVALID，如果键不存在）
            switch (bundle.getInt(ACTION_STRING_NAME, ACTION_INVALID)) {
                // 如果操作类型是启动同步任务
                case ACTION_START_SYNC:
                    // 调用startSync方法启动同步任务
                    startSync();
                    break;
                // 如果操作类型是取消同步任务
                case ACTION_CANCEL_SYNC:
                    // 调用cancelSync方法取消同步任务
                    cancelSync();
                    break;
                default:
                    break;
            }
            // 返回START_STICKY，表示服务在被系统强制关闭后（如内存不足等情况），会尝试重新创建并启动，保持服务的持续可用性（但不会重新传递之前的Intent）
            return START_STICKY;
        }
        // 如果不符合上述条件，调用父类的onStartCommand方法进行默认处理
        return super.onStartCommand(intent, flags, startId);
    }

    // 重写Service的onLowMemory方法，当系统内存不足时被调用，在这里如果有正在执行的同步任务，则取消该任务，释放内存资源
    @Override
    public void onLowMemory() {
        if (mSyncTask!= null) {
            mSyncTask.cancelSync();
        }
    }

    // 重写Service的onBind方法，用于处理绑定服务的情况，这里返回null，表示该服务不支持绑定操作
    public IBinder onBind(Intent intent) {
        return null;
    }

    // 公共方法，用于发送包含同步相关状态信息（是否正在同步以及进度消息）的广播，更新同步进度消息并构建广播Intent发送出去
    public void sendBroadcast(String msg) {
        // 更新同步进度消息
        mSyncProgress = msg;
        // 创建一个新的Intent，设置其动作（Action）为之前定义的GTask同步服务广播的动作名称，用于标识该广播的来源和用途
        Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
        // 向广播Intent中添加Extra数据，设置是否正在同步的状态，通过判断mSyncTask是否为null来确定（不为null表示正在同步）
        intent.putExtra(GTASK_SERVICE_BROADCAST_IS_SYNCING, mSyncTask!= null);
        // 向广播Intent中添加Extra数据，设置同步进度消息，使用传入的msg参数作为消息内容
        intent.putExtra(GTASK_SERVICE_BROADCAST_PROGRESS_MSG, msg);
        // 发送广播，将包含同步相关信息的Intent广播出去，以便其他组件可以接收并处理这些信息
        sendBroadcast(intent);
    }

    // 静态公共方法，用于从Activity中启动同步任务，设置相关的Activity上下文到GTaskManager，并发送启动同步任务的Intent到GTaskSyncService
    public static void startSync(Activity activity) {
        GTaskManager.getInstance().setActivityContext(activity);
        Intent intent = new Intent(activity, GTaskSyncService.class);
        intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_START_SYNC);
        activity.startService(intent);
    }

    // 静态公共方法，用于从给定的上下文（通常是Activity或其他组件所在的上下文）中取消同步任务，发送取消同步任务的Intent到GTaskSyncService
    public static void cancelSync(Context context) {
        Intent intent = new Intent(context, GTaskSyncService.class);
        intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_CANCEL_SYNC);
        context.startService(intent);
    }

    // 静态公共方法，用于判断当前是否有正在执行的同步任务，通过检查mSyncTask是否为null来确定，返回布尔值表示同步状态
    public static boolean isSyncing() {
        return mSyncTask!= null;
    }

    // 静态公共方法，用于获取当前的同步进度消息，返回保存同步进度消息的字符串变量的值
    public static String getProgressString() {
        return mSyncProgress;
    }
}