1/*
2 * Copyright (C) 2013 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17
18package com.android.mail.providers;
19
20import com.android.mail.ui.FolderController;
21import com.android.mail.utils.LogTag;
22import com.android.mail.utils.LogUtils;
23
24import android.database.DataSetObserver;
25
26/**
27 * A simple extension of {@link android.database.DataSetObserver} to provide the updated Folder in
28 * {@link #onChanged(Folder)} when the Folder changes. Initializing the object registers with
29 * the observer with the {@link com.android.mail.ui.FolderController} provided. The object will then begin to
30 * receive {@link #onChanged(Folder)} till {@link #unregisterAndDestroy()} is called.
31 * <p>
32 * To implement an {@link FolderObserver}, you need to implement the {@link #onChanged(Folder)}
33 * method.
34 */
35public abstract class FolderObserver extends DataSetObserver {
36    /**
37     * The FolderController that the observer is registered with.
38     */
39    private FolderController mController;
40
41    private static final String LOG_TAG = LogTag.getLogTag();
42
43    /**
44     * The no-argument constructor leaves the object unusable till
45     * {@link #initialize(FolderController)} is called.
46     */
47    public FolderObserver () {
48    }
49
50    /**
51     * Initializes an {@link FolderObserver} object that receives a call to
52     * {@link #onChanged(Folder)} when the controller changes the Folder.
53     *
54     * @param controller
55     */
56    public Folder initialize(FolderController controller) {
57        if (controller == null) {
58            LogUtils.wtf(LOG_TAG, "FolderObserver initialized with null controller!");
59        }
60        mController = controller;
61        mController.registerFolderObserver(this);
62        return mController.getFolder();
63    }
64
65    @Override
66    public final void onChanged() {
67        if (mController == null) {
68            return;
69        }
70        onChanged(mController.getFolder());
71    }
72
73    /**
74     * Callback invoked when the Folder object is changed.  Since {@link Folder} objects are
75     * immutable, updates can be received on changes to individual settings (sync on/off)
76     * in addition to changes of Folders: alice@example.com -> bob@example.com.
77     * The updated Folder is passed as the argument.
78     * @param newFolder
79     */
80    public abstract void onChanged(Folder newFolder);
81
82    /**
83     * Return the current folder.
84     * @return
85     */
86    public final Folder getFolder() {
87        if (mController == null) {
88            return null;
89        }
90        return mController.getFolder();
91    }
92
93    /**
94     * Unregisters for Folder changes and makes the object unusable.
95     */
96    public void unregisterAndDestroy() {
97        if (mController == null) {
98            return;
99        }
100        mController.unregisterFolderObserver(this);
101    }
102}
103