1 /* 2 * Copyright (C) 2015 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 package com.android.messaging.datamodel.binding; 17 18 /** 19 * The binding class keeps track of a binding between a ui component and an item of BindableData 20 * It allows each side to ensure that when it communicates with the other they are still bound 21 * together. 22 * NOTE: Ensure that the UI component uses the same binding instance for it's whole lifetime 23 * (DO NOT CREATE A NEW BINDING EACH TIME A NEW PIECE OF DATA IS BOUND)... 24 * 25 * The ui component owns the binding instance. 26 * It can use it [isBound(data)] to see if the binding still binds to the right piece of data 27 * 28 * Upon binding the data is informed of a unique binding key generated in this class and can use 29 * that to ensure that it is still issuing callbacks to the right piece of ui. 30 */ 31 public abstract class BindingBase<T extends BindableData> { 32 /** 33 * Creates a new exclusively owned binding for the owner object. 34 */ createBinding(final Object owner)35 public static <T extends BindableData> Binding<T> createBinding(final Object owner) { 36 return new Binding<T>(owner); 37 } 38 39 /** 40 * Creates a new read-only binding referencing the source binding object. 41 * TODO: We may want to refcount the Binding references, so that when the binding owner 42 * calls unbind() when there's still outstanding references we can catch it. 43 */ createBindingReference( final BindingBase<T> srcBinding)44 public static <T extends BindableData> ImmutableBindingRef<T> createBindingReference( 45 final BindingBase<T> srcBinding) { 46 return new ImmutableBindingRef<T>(srcBinding); 47 } 48 49 /** 50 * Creates a detachable binding for the owner object. Use this if your owner object is a UI 51 * component that may undergo a "detached from window" -> "re-attached to window" transition. 52 */ createDetachableBinding( final Object owner)53 public static <T extends BindableData> DetachableBinding<T> createDetachableBinding( 54 final Object owner) { 55 return new DetachableBinding<T>(owner); 56 } 57 getData()58 public abstract T getData(); 59 60 /** 61 * Check if binding connects to the specified data instance 62 */ isBound()63 public abstract boolean isBound(); 64 65 /** 66 * Check if binding connects to the specified data instance 67 */ isBound(final T data)68 public abstract boolean isBound(final T data); 69 70 /** 71 * Throw if binding connects to the specified data instance 72 */ ensureBound()73 public abstract void ensureBound(); 74 75 /** 76 * Throw if binding connects to the specified data instance 77 */ ensureBound(final T data)78 public abstract void ensureBound(final T data); 79 80 /** 81 * Return the binding id for this binding (will be null if not bound) 82 */ getBindingId()83 public abstract String getBindingId(); 84 } 85