Executar um adaptador de sincronização

Observação:recomendamos o WorkManager como a solução para a maioria dos casos de uso de processamento em segundo plano. Consulte o guia de processamento em segundo plano para saber qual solução funciona melhor para você.

Nas lições anteriores desta aula, você aprendeu a criar um componente de adaptador de sincronização que encapsula o código de transferência de dados e a adicionar outros componentes que permitem conectar o adaptador de sincronização ao sistema. Agora você tem tudo o que precisa para instalar um app que inclua um adaptador de sincronização, mas nenhum dos códigos que você viu executa o adaptador de sincronização.

Tente executar o adaptador de sincronização com base em uma programação ou como resultado indireto de algum evento. Por exemplo, você pode querer que o adaptador de sincronização seja executado regularmente, após um determinado período ou em um horário específico do dia. Execute o adaptador de sincronização quando houver mudanças nos dados armazenados no dispositivo. Evite executar o adaptador de sincronização como resultado direto de uma ação do usuário, já que, ao fazer isso, você não aproveita todos os benefícios da capacidade de agendamento do framework do adaptador de sincronização. Por exemplo, evite fornecer um botão de atualização na interface do usuário.

Você tem as seguintes opções para executar o adaptador de sincronização:

Quando os dados do servidor são alterados

Execute o adaptador de sincronização em resposta a uma mensagem de um servidor, indicando que os dados com base no servidor mudaram. Essa opção permite que você atualize dados do servidor no dispositivo sem prejudicar o desempenho ou desperdiçar a duração da bateria pesquisando o servidor.

Quando os dados do dispositivo forem modificados

Execute um adaptador de sincronização quando os dados forem modificados no dispositivo. Essa opção permite enviar dados modificados do dispositivo para um servidor e é especialmente útil se você precisa garantir que o servidor sempre tenha os dados mais recentes do dispositivo. Essa opção é simples de implementar se você realmente armazena dados no seu provedor de conteúdo. Se você está usando um provedor de conteúdo stub, pode ser mais difícil detectar alterações nos dados.

Em intervalos regulares

Execute um adaptador de sincronização após a expiração de um intervalo escolhido ou em um determinado horário todos os dias.

Sob demanda

Execute o adaptador de sincronização em resposta a uma ação do usuário. No entanto, para oferecer a melhor experiência do usuário, use uma das opções mais automatizadas. Usando opções automatizadas, você economiza bateria e recursos da rede.

O restante desta lição descreve cada uma das opções com mais detalhes.

Executar o adaptador de sincronização quando os dados do servidor são modificados

Se o app transferir dados de um servidor e os dados dele mudarem com frequência, você poderá usar um adaptador de sincronização para fazer downloads em resposta a essas mudanças. Para executar o adaptador de sincronização, configure o servidor para enviar uma mensagem especial para uma BroadcastReceiver no app. Em resposta a essa mensagem, chame ContentResolver.requestSync() para sinalizar o framework do adaptador de sincronização e executar o adaptador de sincronização.

O Google Cloud Messaging (GCM) fornece os componentes do servidor e do dispositivo necessários para que o sistema de mensagens funcione. O uso do GCM para acionar transferências é mais confiável e mais eficiente do que a pesquisa de status em servidores. Embora a pesquisa exija um Service que esteja sempre ativo, o GCM usa um BroadcastReceiver que é ativado quando uma mensagem chega. Embora a pesquisa em intervalos regulares use energia da bateria, mesmo que não haja atualizações disponíveis, o GCM só envia mensagens quando necessário.

Observação: se você usar o GCM para acionar o adaptador de sincronização por meio de uma transmissão para todos os dispositivos em que o app estiver instalado, lembre-se de que eles recebem a mensagem mais ou menos ao mesmo tempo. Essa situação pode fazer com que várias instâncias do adaptador de sincronização sejam executadas ao mesmo tempo, causando sobrecarga no servidor e na rede. Para evitar essa situação em uma transmissão para todos os dispositivos, considere adiar o início do adaptador de sincronização por um período exclusivo para cada dispositivo.

O snippet de código a seguir mostra como executar requestSync() em resposta ao recebimento de uma mensagem do GCM.

...
// Constants
// Content provider authority
const val AUTHORITY = "com.example.android.datasync.provider"
// Account type
const val ACCOUNT_TYPE = "com.example.android.datasync"
// Account
const val ACCOUNT = "default_account"
// Incoming Intent key for extended data
const val KEY_SYNC_REQUEST = "com.example.android.datasync.KEY_SYNC_REQUEST"
...
class GcmBroadcastReceiver : BroadcastReceiver() {
    ...
    override fun onReceive(context: Context, intent: Intent) {
        // Get a GCM object instance
        val gcm: GoogleCloudMessaging = GoogleCloudMessaging.getInstance(context)
        // Get the type of GCM message
        val messageType: String? = gcm.getMessageType(intent)
        /*
         * Test the message type and examine the message contents.
         * Since GCM is a general-purpose messaging system, you
         * may receive normal messages that don't require a sync
         * adapter run.
         * The following code tests for a a boolean flag indicating
         * that the message is requesting a transfer from the device.
         */
        if (GoogleCloudMessaging.MESSAGE_TYPE_MESSAGE == messageType
            && intent.getBooleanExtra(KEY_SYNC_REQUEST, false)) {
            /*
             * Signal the framework to run your sync adapter. Assume that
             * app initialization has already created the account.
             */
            ContentResolver.requestSync(mAccount, AUTHORITY, null)
            ...
        }
        ...
    }
    ...
}

public class GcmBroadcastReceiver extends BroadcastReceiver {
    ...
    // Constants
    // Content provider authority
    public static final String AUTHORITY = "com.example.android.datasync.provider";
    // Account type
    public static final String ACCOUNT_TYPE = "com.example.android.datasync";
    // Account
    public static final String ACCOUNT = "default_account";
    // Incoming Intent key for extended data
    public static final String KEY_SYNC_REQUEST =
            "com.example.android.datasync.KEY_SYNC_REQUEST";
    ...
    @Override
    public void onReceive(Context context, Intent intent) {
        // Get a GCM object instance
        GoogleCloudMessaging gcm =
                GoogleCloudMessaging.getInstance(context);
        // Get the type of GCM message
        String messageType = gcm.getMessageType(intent);
        /*
         * Test the message type and examine the message contents.
         * Since GCM is a general-purpose messaging system, you
         * may receive normal messages that don't require a sync
         * adapter run.
         * The following code tests for a a boolean flag indicating
         * that the message is requesting a transfer from the device.
         */
        if (GoogleCloudMessaging.MESSAGE_TYPE_MESSAGE.equals(messageType)
            &&
            intent.getBooleanExtra(KEY_SYNC_REQUEST)) {
            /*
             * Signal the framework to run your sync adapter. Assume that
             * app initialization has already created the account.
             */
            ContentResolver.requestSync(mAccount, AUTHORITY, null);
            ...
        }
        ...
    }
    ...
}

Executar o adaptador de sincronização quando os dados do provedor de conteúdo são modificados

Se o app coleta dados em um provedor de conteúdo e você quer atualizar o servidor sempre que o provedor é atualizado, é possível configurar o app para executar o adaptador de sincronização automaticamente. Para fazer isso, registre um observador para o provedor de conteúdo. Quando os dados no provedor de conteúdo mudam, o framework chama o observador. No observador, chame requestSync() para instruir o framework a executar o adaptador de sincronização.

Observação:se você estiver usando um provedor de conteúdo stub, não terá dados no provedor de conteúdo, e onChange() nunca será chamado. Nesse caso, você precisa fornecer um mecanismo próprio para detectar mudanças nos dados do dispositivo. Esse mecanismo também é responsável por chamar requestSync() quando os dados mudam.

Para criar um observador para seu provedor de conteúdo, estenda a classe ContentObserver e implemente as duas formas do método onChange(). Em onChange(), chame requestSync() para iniciar o adaptador de sincronização.

Para registrar o observador, transmita-o como um argumento em uma chamada para registerContentObserver(). Nessa chamada, você também precisa transmitir um URI de conteúdo para os dados que quer observar. O framework do provedor de conteúdo compara esse URI de observação com URIs de conteúdo transmitidos como argumentos para métodos ContentResolver que modificam seu provedor, como ContentResolver.insert(). Se houver uma correspondência, a implementação de ContentObserver.onChange() será chamada.

O snippet de código a seguir mostra como definir um ContentObserver que chama requestSync() quando uma tabela muda.

// Constants
// Content provider scheme
const val SCHEME = "content://"
// Content provider authority
const val AUTHORITY = "com.example.android.datasync.provider"
// Path for the content provider table
const val TABLE_PATH = "data_table"
...
class MainActivity : FragmentActivity() {
    ...
    // A content URI for the content provider's data table
    private lateinit var uri: Uri
    // A content resolver for accessing the provider
    private lateinit var mResolver: ContentResolver
    ...
    inner class TableObserver(...) : ContentObserver(...) {
        /*
         * Define a method that's called when data in the
         * observed content provider changes.
         * This method signature is provided for compatibility with
         * older platforms.
         */
        override fun onChange(selfChange: Boolean) {
            /*
             * Invoke the method signature available as of
             * Android platform version 4.1, with a null URI.
             */
            onChange(selfChange, null)
        }

        /*
         * Define a method that's called when data in the
         * observed content provider changes.
         */
        override fun onChange(selfChange: Boolean, changeUri: Uri?) {
            /*
             * Ask the framework to run your sync adapter.
             * To maintain backward compatibility, assume that
             * changeUri is null.
             */
            ContentResolver.requestSync(account, AUTHORITY, null)
        }
        ...
    }
    ...
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        // Get the content resolver object for your app
        mResolver = contentResolver
        // Construct a URI that points to the content provider data table
        uri = Uri.Builder()
                .scheme(SCHEME)
                .authority(AUTHORITY)
                .path(TABLE_PATH)
                .build()
        /*
         * Create a content observer object.
         * Its code does not mutate the provider, so set
         * selfChange to "false"
         */
        val observer = TableObserver(false)
        /*
         * Register the observer for the data table. The table's path
         * and any of its subpaths trigger the observer.
         */
        mResolver.registerContentObserver(uri, true, observer)
        ...
    }
    ...
}

public class MainActivity extends FragmentActivity {
    ...
    // Constants
    // Content provider scheme
    public static final String SCHEME = "content://";
    // Content provider authority
    public static final String AUTHORITY = "com.example.android.datasync.provider";
    // Path for the content provider table
    public static final String TABLE_PATH = "data_table";
    // Account
    public static final String ACCOUNT = "default_account";
    // Global variables
    // A content URI for the content provider's data table
    Uri uri;
    // A content resolver for accessing the provider
    ContentResolver mResolver;
    ...
    public class TableObserver extends ContentObserver {
        /*
         * Define a method that's called when data in the
         * observed content provider changes.
         * This method signature is provided for compatibility with
         * older platforms.
         */
        @Override
        public void onChange(boolean selfChange) {
            /*
             * Invoke the method signature available as of
             * Android platform version 4.1, with a null URI.
             */
            onChange(selfChange, null);
        }
        /*
         * Define a method that's called when data in the
         * observed content provider changes.
         */
        @Override
        public void onChange(boolean selfChange, Uri changeUri) {
            /*
             * Ask the framework to run your sync adapter.
             * To maintain backward compatibility, assume that
             * changeUri is null.
             */
            ContentResolver.requestSync(mAccount, AUTHORITY, null);
        }
        ...
    }
    ...
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        // Get the content resolver object for your app
        mResolver = getContentResolver();
        // Construct a URI that points to the content provider data table
        uri = new Uri.Builder()
                  .scheme(SCHEME)
                  .authority(AUTHORITY)
                  .path(TABLE_PATH)
                  .build();
        /*
         * Create a content observer object.
         * Its code does not mutate the provider, so set
         * selfChange to "false"
         */
        TableObserver observer = new TableObserver(false);
        /*
         * Register the observer for the data table. The table's path
         * and any of its subpaths trigger the observer.
         */
        mResolver.registerContentObserver(uri, true, observer);
        ...
    }
    ...
}

Executar o adaptador de sincronização periodicamente

Você pode executar o adaptador de sincronização periodicamente definindo um período de espera entre as execuções, executando-o em determinados horários do dia ou ambos. A execução periódica do adaptador de sincronização permite que você corresponda aproximadamente ao intervalo de atualização do servidor.

Da mesma forma, você pode fazer upload de dados do dispositivo quando o servidor estiver relativamente inativo, programando o adaptador de sincronização para ser executado à noite. A maioria dos usuários deixa os dispositivos ligados e conectados à noite, então esse horário geralmente está disponível. Além disso, o dispositivo não está executando outras tarefas ao mesmo tempo que o adaptador de sincronização. No entanto, se você adotar essa abordagem, precisará garantir que cada dispositivo acione uma transferência de dados em um horário um pouco diferente. Se todos os dispositivos executarem o adaptador de sincronização ao mesmo tempo, é provável que você sobrecarregue as redes de dados do servidor e do provedor de rede celular.

Em geral, as execuções periódicas fazem sentido quando os usuários não precisam de atualizações instantâneas, mas esperam atualizações regulares. Execuções periódicas também fazem sentido se você quiser equilibrar a disponibilidade de dados atualizados com a eficiência de execuções menores do adaptador de sincronização que não usam os recursos do dispositivo em excesso.

Para executar o adaptador de sincronização em intervalos regulares, chame addPeriodicSync(). Isso programa o adaptador de sincronização para ser executado após um determinado período. Como o framework do adaptador de sincronização precisa considerar outras execuções do adaptador de sincronização e tenta maximizar a eficiência da bateria, o tempo decorrido pode variar em alguns segundos. Além disso, o framework não executará o adaptador de sincronização se a rede não estiver disponível.

Observe que addPeriodicSync() não executa o adaptador de sincronização em um horário específico do dia. Para executar o adaptador de sincronização aproximadamente à mesma hora todos os dias, use um alarme de repetição como gatilho. Alarmes de repetição são descritos com mais detalhes na documentação de referência para AlarmManager. Se você usar o método setInexactRepeating() para definir gatilhos por hora do dia com alguma variação, ainda será necessário randomizar o horário de início para garantir que o adaptador de sincronização seja executado em diferentes dispositivos de maneira escalonada.

O método addPeriodicSync() não desativa setSyncAutomatically(). Portanto, você pode ter várias execuções de sincronização em um período relativamente curto. Além disso, apenas algumas flags de controle do adaptador de sincronização são permitidas em uma chamada para addPeriodicSync(). As sinalizações não permitidas são descritas na documentação referenciada para addPeriodicSync().

O snippet de código a seguir mostra como programar execuções periódicas do adaptador de sincronização.

// Content provider authority
const val AUTHORITY = "com.example.android.datasync.provider"
// Account
const val ACCOUNT = "default_account"
// Sync interval constants
const val SECONDS_PER_MINUTE = 60L
const val SYNC_INTERVAL_IN_MINUTES = 60L
const val SYNC_INTERVAL = SYNC_INTERVAL_IN_MINUTES * SECONDS_PER_MINUTE
...
class MainActivity : FragmentActivity() {
    ...
    // A content resolver for accessing the provider
    private lateinit var mResolver: ContentResolver

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        // Get the content resolver for your app
        mResolver = contentResolver
        /*
         * Turn on periodic syncing
         */
        ContentResolver.addPeriodicSync(
                mAccount,
                AUTHORITY,
                Bundle.EMPTY,
                SYNC_INTERVAL)
        ...
    }
    ...
}

public class MainActivity extends FragmentActivity {
    ...
    // Constants
    // Content provider authority
    public static final String AUTHORITY = "com.example.android.datasync.provider";
    // Account
    public static final String ACCOUNT = "default_account";
    // Sync interval constants
    public static final long SECONDS_PER_MINUTE = 60L;
    public static final long SYNC_INTERVAL_IN_MINUTES = 60L;
    public static final long SYNC_INTERVAL =
            SYNC_INTERVAL_IN_MINUTES *
            SECONDS_PER_MINUTE;
    // Global variables
    // A content resolver for accessing the provider
    ContentResolver mResolver;
    ...
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        // Get the content resolver for your app
        mResolver = getContentResolver();
        /*
         * Turn on periodic syncing
         */
        ContentResolver.addPeriodicSync(
                mAccount,
                AUTHORITY,
                Bundle.EMPTY,
                SYNC_INTERVAL);
        ...
    }
    ...
}

Executar o adaptador de sincronização sob demanda

A execução do adaptador de sincronização em resposta a uma solicitação do usuário é a estratégia menos recomendada. O framework foi projetado especificamente para economizar bateria ao executar adaptadores de sincronização de acordo com uma programação. As opções que executam uma sincronização em resposta a mudanças de dados usam a energia da bateria de forma eficaz, já que ela é usada para fornecer novos dados.

Em comparação, permitir que os usuários executem uma sincronização sob demanda significa que a sincronização será executada sozinha, o que representa um uso ineficiente da rede e dos recursos de energia. Além disso, fornecer sincronização sob demanda leva os usuários a solicitar uma sincronização, mesmo que não haja evidências de que os dados foram modificados. Executar uma sincronização que não atualize os dados é um uso ineficaz da bateria. Em geral, seu app precisa usar outros sinais para acionar uma sincronização ou programá-los em intervalos regulares, sem a necessidade de entrada do usuário.

No entanto, se você ainda quiser executar o adaptador de sincronização sob demanda, defina as sinalizações para uma execução manual e chame ContentResolver.requestSync().

Gerencie transferências sob demanda com as seguintes sinalizações:

SYNC_EXTRAS_MANUAL

Força uma sincronização manual. O framework do adaptador de sincronização ignora as configurações já existentes, como a sinalização definida por setSyncAutomatically().

SYNC_EXTRAS_EXPEDITED

Força o início imediato da sincronização. Se você não definir isso, o sistema poderá aguardar vários segundos antes de executar a solicitação de sincronização, porque ele tenta otimizar o uso da bateria programando muitas solicitações em um curto período.

O snippet de código a seguir mostra como chamar requestSync() em resposta a um clique no botão:

// Constants
// Content provider authority
val AUTHORITY = "com.example.android.datasync.provider"
// Account type
val ACCOUNT_TYPE = "com.example.android.datasync"
// Account
val ACCOUNT = "default_account"
...
class MainActivity : FragmentActivity() {
    ...
    // Instance fields
    private lateinit var mAccount: Account
    ...
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        /*
         * Create the placeholder account. The code for CreateSyncAccount
         * is listed in the lesson Creating a Sync Adapter
         */

        mAccount = createSyncAccount()
        ...
    }

    /**
     * Respond to a button click by calling requestSync(). This is an
     * asynchronous operation.
     *
     * This method is attached to the refresh button in the layout
     * XML file
     *
     * @param v The View associated with the method call,
     * in this case a Button
     */
    fun onRefreshButtonClick(v: View) {
        // Pass the settings flags by inserting them in a bundle
        val settingsBundle = Bundle().apply {
            putBoolean(ContentResolver.SYNC_EXTRAS_MANUAL, true)
            putBoolean(ContentResolver.SYNC_EXTRAS_EXPEDITED, true)
        }
        /*
         * Request the sync for the default account, authority, and
         * manual sync settings
         */
        ContentResolver.requestSync(mAccount, AUTHORITY, settingsBundle)
    }

public class MainActivity extends FragmentActivity {
    ...
    // Constants
    // Content provider authority
    public static final String AUTHORITY =
            "com.example.android.datasync.provider";
    // Account type
    public static final String ACCOUNT_TYPE = "com.example.android.datasync";
    // Account
    public static final String ACCOUNT = "default_account";
    // Instance fields
    Account mAccount;
    ...
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        /*
         * Create the placeholder account. The code for CreateSyncAccount
         * is listed in the lesson Creating a Sync Adapter
         */

        mAccount = CreateSyncAccount(this);
        ...
    }
    /**
     * Respond to a button click by calling requestSync(). This is an
     * asynchronous operation.
     *
     * This method is attached to the refresh button in the layout
     * XML file
     *
     * @param v The View associated with the method call,
     * in this case a Button
     */
    public void onRefreshButtonClick(View v) {
        // Pass the settings flags by inserting them in a bundle
        Bundle settingsBundle = new Bundle();
        settingsBundle.putBoolean(
                ContentResolver.SYNC_EXTRAS_MANUAL, true);
        settingsBundle.putBoolean(
                ContentResolver.SYNC_EXTRAS_EXPEDITED, true);
        /*
         * Request the sync for the default account, authority, and
         * manual sync settings
         */
        ContentResolver.requestSync(mAccount, AUTHORITY, settingsBundle);
    }