1/*
2 * Copyright (C) 2007 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.dx.dex.file;
18
19import com.android.dx.util.AnnotatedOutput;
20
21/**
22 * Base class for any structurally-significant and (potentially)
23 * repeated piece of a Dalvik file.
24 */
25public abstract class Item {
26    /**
27     * Constructs an instance.
28     */
29    public Item() {
30        // This space intentionally left blank.
31    }
32
33    /**
34     * Returns the item type for this instance.
35     *
36     * @return {@code non-null;} the item type
37     */
38    public abstract ItemType itemType();
39
40    /**
41     * Returns the human name for the particular type of item this
42     * instance is.
43     *
44     * @return {@code non-null;} the name
45     */
46    public final String typeName() {
47        return itemType().toHuman();
48    }
49
50    /**
51     * Gets the size of this instance when written, in bytes.
52     *
53     * @return {@code >= 0;} the write size
54     */
55    public abstract int writeSize();
56
57    /**
58     * Populates a {@link DexFile} with items from within this instance.
59     * This will <i>not</i> add an item to the file for this instance itself
60     * (which should have been done by whatever refers to this instance).
61     *
62     * <p><b>Note:</b> Subclasses must override this to do something
63     * appropriate.</p>
64     *
65     * @param file {@code non-null;} the file to populate
66     */
67    public abstract void addContents(DexFile file);
68
69    /**
70     * Writes the representation of this instance to the given data section,
71     * using the given {@link DexFile} to look things up as needed.
72     * If this instance keeps track of its offset, then this method will
73     * note the written offset and will also throw an exception if this
74     * instance has already been written.
75     *
76     * @param file {@code non-null;} the file to use for reference
77     * @param out {@code non-null;} where to write to
78     */
79    public abstract void writeTo(DexFile file, AnnotatedOutput out);
80}
81