ImapElement.java revision ee6d0d47f58ac8d010cbc68014e6786da696e726 
1/*
2 * Copyright (C) 2010 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
17package com.android.email.mail.store.imap;
18
19/**
20 * Class representing "element"s in IMAP responses.
21 *
22 * <p>Class hierarchy:
23 * <pre>
24 * ImapElement
25 *   |
26 *   |-- ImapElement.NONE (for 'index out of range')
27 *   |
28 *   |-- ImapList (isList() == true)
29 *   |   |
30 *   |   |-- ImapList.EMPTY
31 *   |   |
32 *   |   --- ImapResponse
33 *   |
34 *   --- ImapString (isString() == true)
35 *       |
36 *       |-- ImapString.EMPTY
37 *       |
38 *       |-- ImapSimpleString
39 *       |
40 *       |-- ImapMemoryLiteral
41 *       |
42 *       --- ImapTempFileLiteral
43 * </pre>
44 */
45public abstract class ImapElement {
46    /**
47     * An element that is returned by {@link ImapList#getElementOrNone} to indicate an index
48     * is out of range.
49     */
50    public static final ImapElement NONE = new ImapElement() {
51        @Override public void destroy() {
52            // Don't call super.destroy().
53            // It's a shared object.  We don't want the mDestroyed to be set on this.
54        }
55
56        @Override public boolean isList() {
57            return false;
58        }
59
60        @Override public boolean isString() {
61            return false;
62        }
63
64        @Override public String toString() {
65            return "[NO ELEMENT]";
66        }
67
68        @Override
69        public boolean equalsForTest(ImapElement that) {
70            return super.equalsForTest(that);
71        }
72    };
73
74    private boolean mDestroyed = false;
75
76    public abstract boolean isList();
77
78    public abstract boolean isString();
79
80    protected boolean isDestroyed() {
81        return mDestroyed;
82    }
83
84    /**
85     * Clean up the resources used by the instance.
86     * It's for removing a temp file used by {@link ImapTempFileLiteral}.
87     */
88    public void destroy() {
89        mDestroyed = true;
90    }
91
92    /**
93     * Throws {@link RuntimeException} if it's already destroyed.
94     */
95    protected final void checkNotDestroyed() {
96        if (mDestroyed) {
97            throw new RuntimeException("Already destroyed");
98        }
99    }
100
101    /**
102     * Return a string that represents this object; it's purely for the debug purpose.  Don't
103     * mistake it for {@link ImapString#getString}.
104     *
105     * Abstract to force subclasses to implement it.
106     */
107    @Override
108    public abstract String toString();
109
110    /**
111     * The equals implementation that is intended to be used only for unit testing.
112     * (Because it may be heavy and has a special sense of "equal" for testing.)
113     */
114    public boolean equalsForTest(ImapElement that) {
115        if (that == null) {
116            return false;
117        }
118        return this.getClass() == that.getClass(); // Has to be the same class.
119    }
120}
121