com.android.ide.common.res2.DataItem Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of sdk-common Show documentation
sdk-common library used by other Android tools libraries.
There is a newer version: 25.3.0
/*
 * Copyright (C) 2012 The Android Open Source Project
 *
 * 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 com.android.ide.common.res2;

import com.android.annotations.NonNull;
import com.android.annotations.Nullable;
import com.google.common.base.Objects;

import org.w3c.dom.Document;
import org.w3c.dom.Node;

import java.io.File;

/**
 * A data item is the most elementary merge unit in the data merging process. Data items will
 * generally belong to a {@link DataFile} although, temporarily during the merge process data
 * items may not be associated to any data file. This will happen when data items are moved from
 * one file to another.
 *
 * Data items can represent entire files, e.g., a PNG file, or they can represent
 * individual entries in a file, e.g., a string in a strings file.
 *
 * Data items have three markers that represent its "state": touched, removed and written.
 * A touched data is a data item that needs to be examined in the merge process. A removed data
 * item is a data item that has been removed from its file. A written data item is a data item
 * that has been changed or added.
 *
 * @param  the type of data file the item belongs to
 */
abstract class DataItem {
    /** Bit flag marking {@link #mStatus} as touched. */
    private static final int MASK_TOUCHED = 0x01;

    /** Bit flag marking {@link #mStatus} as removed. */
    private static final int MASK_REMOVED = 0x02;

    /** Bit flag marking {@link #mStatus} as written. */
    private static final int MASK_WRITTEN = 0x10;

    /** Name of the data item. */
    @NonNull private final String mName;

    /** File the data item comes from. */
    @Nullable private F mSource;

    /**
     * The status of the Item. It's a bit mask as opposed to an enum
     * to differentiate removed and removed+written
     */
    private int mStatus = 0;

    /**
     * Constructs the object with a name, type and optional value.
     * Note that the object is not fully usable as-is. It must be added to a DataFile first.
     * @param name the name of the item
     */
    DataItem(@NonNull String name) {
        mName = name;
    }

    /**
     * Returns the name of the item.
     */
    @NonNull
    public String getName() {
        return mName;
    }

    /**
     * Returns the DataFile the item is coming from.
     */
    @Nullable
    public F getSource() {
        return mSource;
    }

    /**
     * Sets the DataFile. The item must not belong to a data file.
     * @param sourceFile the data file, if null then the item is marked as being removed from the
     *                   data file
     */
    public void setSource(@NonNull F sourceFile) {
        mSource = sourceFile;
    }

    /**
     * Resets the state of the item be nothing.
     * @return this
     */
    DataItem resetStatus() {
        mStatus = 0;
        return this;
    }

    /**
     * Resets the state of the item be WRITTEN. All other states are removed.
     * @return this
     * @see #isWritten()
     */
    DataItem resetStatusToWritten() {
        mStatus = MASK_WRITTEN;
        return this;
    }

    /**
     * Resets the state of the item be TOUCHED. All other states are removed.
     * @return this
     * @see #isWritten()
     */
    DataItem resetStatusToTouched() {
        boolean wasNotTouched = !isTouched();
        mStatus = MASK_TOUCHED;

        if (!wasNotTouched) {
            wasTouched();
        }

        return this;
    }

    /**
     * Sets the item status to contain WRITTEN. Other states are kept.
     * @return this
     * @see #isWritten()
     */
    DataItem setWritten() {
        mStatus |= MASK_WRITTEN;
        return this;
    }

    /**
     * Sets the item status to contain REMOVED. Other states are kept.
     * @return this
     * @see #isRemoved()
     */
    DataItem setRemoved() {
        mStatus |= MASK_REMOVED;
        return this;
    }

    /**
     * Sets the item status to contain TOUCHED. Other states are kept.
     * @return this
     * @see #isTouched()
     */
    DataItem setTouched() {
        if (!isTouched()) {
            mStatus |= MASK_TOUCHED;
            wasTouched();
        }

        return this;
    }

    /**
     * Returns whether the item status contains REMOVED.
     * @return true if removed
     */
    boolean isRemoved() {
        return (mStatus & MASK_REMOVED) != 0;
    }

    /**
     * Returns whether the item status contains TOUCHED
     * @return true if touched
     */
    boolean isTouched() {
        return (mStatus & MASK_TOUCHED) != 0;
    }

    /**
     * Returns whether the item status contains WRITTEN
     * @return true if written
     */
    boolean isWritten() {
        return (mStatus & MASK_WRITTEN) != 0;
    }


    /**
     * Obtains the full status of the data item; should not generally be used except
     * for debug purposes.
     * @return the internal representation
     */
    protected int getStatus() {
        return mStatus;
    }

    /**
     * Returns the key for this item. They key uniquely identifies this item.
     */
    public String getKey() {
        return mName;
    }

    /**
     * Overridden in ResourceItem, which adds the type attribute.
     */
    void addExtraAttributes(Document document, Node node, String namespaceUri) {
        // nothing
    }

    /**
     * Returns a node that describes additional properties of this {@link DataItem}.
     * If not null, it will be persisted in the merger XML blob and can be used
     * used to restore the exact state of this item. If null then the state of this
     * item will not be persisted.
     *
     * The default implementation returns null.
     */
    Node getDetailsXml(Document document) {
        return null;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (o == null || getClass() != o.getClass()) {
            return false;
        }

        DataItem dataItem = (DataItem) o;

        return Objects.equal(mName, dataItem.mName)
                && Objects.equal(mSource, dataItem.mSource);
    }

    @Override
    public int hashCode() {
        return Objects.hashCode(mName, mSource);
    }

    /**
     * Hook invoked when the data item has been touched. The default implementation does nothing.
     */
    protected void wasTouched() {}

    /**
     * For non-values resources, this is the original source file.
     * This method is here as {@link GeneratedResourceItem} overrides it.
     */
    public File getFile() {
        return getSource().getFile();
    }
}