AndroidKVO
this library intend to help android developer to implement something like iOS key value observer pattern (KVO)
What is KVO?
If you came a cross KVO in iOS that feature will certainly caught your eyes, why? well imagine that you have an object in your memory and you want to know if any change happened to that object during the life cycle of your application, well KVO give you that ability but unfortunately android doesn't support that feature
Features supported by Lib
- you can listen to any change happen to a certain field inside a certain object and whenever that reference change you will get notified.
- you can listen to any change happen to a certain field accross all of your models for example imagine that you got an object Person will field called salary and another object Payroll with field called balance but both of the fields are the same well you can give the same id to both fields and whenever a change happen to any of them in any object (even if it's a new object and you didn't assign a listener to it) you will get notified
- no need to worry about memory leak since Lib use only
WeakReference
- if your listener is
Activity
orFragment
before invoke callback the lib will checkisFinishing()
to make sure that they are able to receive callbacks
to simplify the previous the lib give you the ability to be notified on object level or to be notified on application level
How To Use
use jCenter() to download it.
compile 'com.ark.android:AndroidKVO:1.0.1'
annotationProcessor 'com.ark.android:AndroidKVO-Compiler:1.0.0'
- first let us consider you have a model called
Person
with variables such asname
,age
and salary - another object called
Payroll
with only one variable calledbalance
- and 2 activities one called HomeActivity and the other is PayrollDetails where you can change the person variables and payroll variable
- let us imagine that we need to observe any change happen to name,age fields in a particular object (reference) and any change happen to salary in any object new or exist
Implementation
- First inside
Person
class lets annotate it with@AndroidKVO
- Annotate name and age with
@KVOField
- Annotate
salary
with@KVOField(id = "salary")
where ID is any unique string of your choosing - Do the same in Payroll object and annotate balance with same id you gave to salary in our case
@KVOField(id = "salary")
- Your object will look something like that
@AndroidKVO
public class Person {
@KVOField(id = "name")
public String name;
@KVOField
public int age;
@KVOField(id = "salary")
public int salary;
}
- Build your project
- Now you can use two new objects called (yourObject-KVO) so in our case PersonKVO and PayrollKVO
- Inside your HomeActivity implement
KVOListener
and overrideonValueChange(Object affectedObject, Object changedValue, String fieldNameOrId)
- Now init the KVO objects and assign HomeActivity as listener if you need to get notified if any change happen to anyField with KVOField annotation
PersonKVO person = new PersonKVO();
person.setListener(KVOListener);
OR
if you need to get notified only when a change happen to a certain field
person.setListener(KVOListener, PersonKVO.FieldName.name);
- Now pass this object to PayrollDetails activity through intent and change any field by calling the setter the HomeActivity will get notified with the change
- If however we call the following line inside HomeActivity
person.setListenerForId(KVOListener , "salary");
- If we declared a new object (PersonKVO or PayrollKVO) in any other class and we called setSalary or setBalance the HomeActivity will still get notified
Methods provided by lib
FieldName
enum contain all fields name in your modelsetListener()
make class observe for any change happen to any field with@KVOField
annotation and if that field contain ID the lib will add a that listener as an Application level observer (if any change happen to that field in any object new or old the listener will be notified)setListener(KVOListener listener , FieldName property)
make class observe only for that field in that particular object (object level)setListenerForId(KVOListener listener, String id)
set the class as an application level observer for that idremoveListener()
remove that observer from list
License
The MIT License (MIT)
Copyright (c) 2017 Ahmed basyouni
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.