Android Contact数据模型之EntityDelta

public class EntityDelta implements Parcelable

         EntityDelta的数据模型描述：
        EntityDelta是ValuesDelta的集合，它还实现了Parcelable接口。它包含了主数据(存在ValuesDelta mValues中）和子数据.它把子数据以ValuesDelta的形式按照它们的mimetype存放在HashMap<String, ArrayList<ValuesDelta>> mEntries中(拥有相同的mimetype的ValuesDelta放在同一个ArrayList).

       构造函数 ：

       public EntityDelta()
       创建一个空的EntityDelta

       public EntityDelta(ValuesDelta values)
       创建一个EntityDelta，并用ValuesDelta values来初始化主数据。

       主要成员变量 ：

        private ValuesDelta mValues ;
        用于存放 主表 （主数据），

       private HashMap<String, ArrayList<ValuesDelta>> mEntries = Maps.newHashMap() ;
       用于存放 子表 （子数据），子数据以ValuesDelta的形式按照它们的mimetype存放在其中。


       静态成员变量
       public static final Parcelable.Creator<EntityDelta> CREATOR 
       注 ：该变量因Parcelable而设计。

       主要静态函数 ：
       public static EntityDelta fromBefore(Entity before)
       用Entity before来实例化一个EntityDelta,把Entity before的getEntityValues()得到主数据以ValuesDelta.fromBefore的形式打包成ValuesDelta并赋予mValues.且设置mValues的mIdColumn为RawContacts._ID。然后用before.getSubValues()得到子数据,然后以ValuesDelta.fromBefore的形式打包成ValuesDelta并放入mEntries。

       注1 ：这里的Entity before对应一个RawContacts的数据。
       注2 ：该函数在把Entity转化成EntityDelta的过程中，把Entity的子数据的Uri uri丢失了。

       因为对于update操作可以通过ValuesDelta的id就可以确定它的位置（当然Uri uri也可以确定，毕竟Data.CONTENT_URI是固定）。

       对于删除操作，有主数据的信息就可以了。

       public static EntityDelta mergeAfter(EntityDelta local, EntityDelta remote)

       用EntityDelta remote对EntityDelta local进行mergeAfter操作。它主要是通过对EntityDelta local和EntityDelta remote中的ValuesDelta进行相应的ValuesDelta的mergeAfter操作来实现mergeAfter操作。对于主数据是直接对他们进行mergeAfter操作。对于子数据，是对同id(即ValuesDelta的mIdColumn值相同)的ValuesDelta进行mergeAfter操作。最后返回新的EntityDelta local。

        注1 ：EntityDelta local可以为null,这时会创建一个空的EntityDelta以便处理。
        注2 ：mergeAfter操作是针对EntityDelta local而进行，所以它会被改变。

        主要成员函数 ：

        public ValuesDelta getValues()
        返回主数据mValues。

       public boolean isContactInsert()  
       返回是否是Insert操作，通过调用主数据mValues的isInsert()方法来判断。

       public ValuesDelta getPrimaryEntry(String mimeType)
       返回PrimaryEntry

       得到MIME类型为mimeType的PrimaryEntry。找到MIME类型为mimeType的ValuesDelta且它的isPrimary()为true，就返回该ValuesDelta。

       如果没找到但MIME类型为mimeType的ValuesDelta的ArrayList<ValuesDelta>至少有一个，则返回该列表上的第一个ValuesDelta。否则返回null。

       public ValuesDelta getSuperPrimaryEntry(String mimeType)
       返回SuperPrimaryEntry

       它直接调用getSuperPrimaryEntry(mimeType, true)。

       public ValuesDelta getSuperPrimaryEntry(String mimeType, boolean forceSelection)

       返回SuperPrimaryEntry

 原理和getPrimaryEntry(String mimeType)相似。但是只有forceSelection为true的情况下，才在没有找到SuperPrimaryEntry的情况下返回PrimaryEntry，如果PrimaryEntry也没找到，才返回MIME类型为mimeType的ValuesDelta的ArrayList<ValuesDelta>的第一的ValuesDelta，如果ArrayList<ValuesDelta>为空则返回null。

        private ArrayList<ValuesDelta> getMimeEntries(String mimeType, boolean lazyCreate)
        得到指定MIME类型mimeType的ArrayList<ValuesDelta>，如果lazyCreate为true，在IME类型mimeType的ArrayList<ValuesDelta>没被创建的情况下，会创建它并放入HashMap<String, ArrayList<ValuesDelta>> mEntrie中。
        public ArrayList<ValuesDelta> getMimeEntries(String mimeType)
        直接调用getMimeEntries(mimeType, false)。

       public int getMimeEntriesCount(String mimeType, boolean onlyVisible)
       得到指定MIME类型mimeType的ValuesDelta数量。如果onlyVisible是true,则ValuesDelta还必须是isVisible()的。

       public boolean hasMimeEntries(String mimeType)
       返回HashMap<String, ArrayList<ValuesDelta>>中是否有MIME类型mimeType的ArrayList<ValuesDelta>。

       public ValuesDelta addEntry(ValuesDelta entry)
       加入一个ValuesDelta entry。

       public ValuesDelta getEntry(Long childId)
       得到id为Long childId的ValuesDelta

        public int getEntryCount(boolean onlyVisible)
        得到ValuesDelta的数量，如果onlyVisible是true,则ValuesDelta还必须是isVisible()的。

        public boolean equals(Object object)
        返回两个EntityDelta是否相当。只有他们所包括的ValuesDelta一样才相等。
        注：这里的"一样"是指ValuesDelta的equals(Object object)返回true.

        private boolean containsEntry(ValuesDelta entry)
        返回ValuesDelta entry是否已经在了HashMap<String, ArrayList<ValuesDelta>>中。

        public void markDeleted() 
        对包含的所有ValuesDelta进行markDeleted()操作。（这里包括主数据ValuesDelta mValues和子数据 HashMap<String, ArrayList<ValuesDelta>>）

        public String toString()
        把所有ValuesDelta进行转化为String.
        private void possibleAdd(ArrayList<ContentProviderOperation> diff,ContentProviderOperation.Builder builder)

        在builder不为空的情况下，把builder生成的ContentProviderOperation加入到ArrayList<ContentProviderOperation> diff中。

         注1：该方法其实应该是static的才对。不知道为什么google没把它写成静态的。也许是google的失误吧。

         public void buildAssert(ArrayList<ContentProviderOperation> buildInto)

java代码：

1. /**
   
2. * Build a list of {@link ContentProviderOperation} that will assert any
   
3. * "before" state hasn't changed. This is maintained separately so that all
   
4. * asserts can take place before any updates occur.
   
5. */

复制代码

      用主数据mValues的Id和RawContacts.VERSION生产一个RawContacts.CONTENT_URI上的AssertQuery形builder，并加入ArrayList<ContentProviderOperation> buildInto)。
       注 ：该函数的真正意义应该是在对数据库操作时（Provide中）进行数据库更新时 确保数据的一致性 。即数据在我们读到EntityDelta并没有改变过。

       public void buildDiff(ArrayList<ContentProviderOperation> buildInto)
       该函数负责把该EntityDelta转化为ArrayList<ContentProviderOperation>,以便进行数据库操作。它主要是调用ValuesDelta的buildDiff来进行ContentProviderOperation，然后把他们整合起来。

       注1 ：对于全新的插入操作，需要在操作前把主表mValues的RawContacts.AGGREGATION_MODE设置为RawContacts.AGGREGATION_MODE_SUSPENDED，等子数据都插入完了才设置为RawContacts.AGGREGATION_MODE_DEFAULT。
       注2 ：对于更新操作，但是子数据有插入操作的同上。
       注3 ：如果主数据时插入操作，那么子数据也必须是插入操作，否则会抛异常。
       注4 ：对于全EntityDelta的删除操作，只需要主表的信息就可以了，因为它的每个子表都存有主表的Id(即Data.RAW_CONTACT_ID).
       注5 ：创建AssertQuery形的builder，可用这样的形式：final ContentProviderOperation.Builder builder = ContentProviderOperation.newAssertQuery(RawContacts.CONTENT_URI)

       protected Builder buildSetAggregationMode(Long beforeId, int mode)
       用Long beforeId, int mode生成update的Builder。

       public int describeContents()
       返回0.// Nothing special about this parcel
       注 ：该方法来自Parcelable。

       public void writeToParcel(Parcel dest, int flags)
       把主表和子表数据都写到Parcel。
       注 ：该方法来自Parcelable。

       public void readFromParcel(Parcel source)
       从Parcel source中读取主表和子表数据。