diff --git a/README.md b/README.md index 6253337..219dd88 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,182 @@ -
+
Яхонт делает невозможное Yakhont - break limits now
- -# Yakhont: high-level Android components for data loading, location, lifecycle callbacks and more + +# Yakhont: high-level Android components for data loading, location, lifecycle callbacks and many more Yakhont is an Android high-level library offering developer-defined callbacks, -loader wrappers, cache, location-awareness, permissions handling, lifecycle debug classes, -advanced logging and many more helpful developer-oriented issues. +loader wrappers, fully automatic cache, location-awareness, dynamic permissions handling, +lifecycle debug classes, advanced logging and many more helpful developer-oriented issues. + +Now you can load data in just one line of code (please refer to the +[simplified demo](yakhont-demo-simple/src/main/java/akha/yakhont/demosimple/MainFragment.java) +for working example): + +```groovy +new Retrofit2CoreLoadBuilder<>(/* your parameters */).create().startLoading(); +``` + +And take location in just a couple of lines (the working example is in the +[simplified demo](yakhont-demo-simple/src/main/java/akha/yakhont/demosimple/MainActivity.java) +too): -It extends the [Application.ActivityLifecycleCallbacks](https://developer.android.com/reference/android/app/Application.ActivityLifecycleCallbacks.html) +```groovy +@CallbacksInherited(LocationCallbacks.class) +public class YourActivity extends Activity implements LocationListener { + @Override + public void onLocationChanged(Location location, Date date) { + // your code here + } +} +``` + +Yakhont extends the [Application.ActivityLifecycleCallbacks](https://developer.android.com/reference/android/app/Application.ActivityLifecycleCallbacks.html) approach to support your own callbacks creation, that allows to customize handling of almost every lifecycle state of your Activities and Fragments - and even without changing their sources (especially useful for libraries developers). -Powerful loader wrappers, which allows loading data in just one line of code, are abstracting -you away from things like loaders management, data binding and caching, progress dialogs -(fully customizable), errors handling and low-level threading; -don't miss the swipe refresh and Rx support too. +The powerful loader wrappers, which (in simplest, but very typical case) allows loading data +in one line of code, are abstracting you away from things like loaders management, data binding +and caching, progress dialogs (fully customizable), errors handling and low-level threading; +don't miss the swipe refresh and both Rx and Rx2 support too. -In short, the data loader features are: +In short, the data loaders features are: - fully asynchronous -- forced timeout -- transparent cache +- forced timeouts +- automatic and absolutely transparent cache - both [RxJava](https://github.com/ReactiveX/RxJava/tree/1.x) and [RxJava 2](https://github.com/ReactiveX/RxJava) support - both [Retrofit](http://square.github.io/retrofit/1.x/retrofit/) and [Retrofit 2](http://square.github.io/retrofit/2.x/retrofit/) support - swipe-to-refresh - device orientation changing support -- fully customizable GUI progress (via Dagger 2) - -Other features includes: -- out-of-the-box location awareness: just annotate your Activity and you're done +- fully customizable GUI progress (via Dagger 2) +- and last but not least: if Retrofit does not meet your requirements, +support for any other libraries can be added easily + +In addition, there are the location features which includes: +- both new ([FusedLocationProviderClient](https://developers.google.com/android/reference/com/google/android/gms/location/FusedLocationProviderClient)-based) +and old ([GoogleApiClient](https://developers.google.com/android/reference/com/google/android/gms/common/api/GoogleApiClient)-based) +Google Location API support +- completely auto (but fully customizable via callbacks) permission handling +- tons of boilerplate code are not needed anymore - just annotate your Activity +- Rx support (both [RxJava](https://github.com/ReactiveX/RxJava/tree/1.x) and [RxJava 2](https://github.com/ReactiveX/RxJava)) + +So, the features Yakhont provides are: +- powerful (but very easy in use) data loaders - self-configurable transparent cache which adjusts database structure 'on the fly' +- out-of-the-box location awareness: just annotate your Activity and you're done +- dynamic permissions handling, powered by user-defined callbacks - debug classes with strict mode and lifecycle logging - for all kinds of -Activities and Fragments (can be enabled even for 3rd-party components) +Activities and Fragments (can be enabled even for 3rd-party components via simple, +but effective Yakhont preprocessor) - advanced logging with e-mail support (auto-disabled in release builds) and more. All Activities and Fragments are supported: it's not necessary to derive them from any predefined ones (with one exception - you will need it for lifecycle debug). -The Yakhont AAR is about 300 KB (except the _full_ version, which is about 500 KB). +The Yakhont AAR is about 320 KB (except the _full_ version, which is about 530 KB). Yakhont supports Android 2.3 (API level 9) and above (_core_ version requires Android 3.0 (API level 11) as a minimum). -**Note:** Location API requires Android 4.0 (API level 14). +**Note:** Location API requires Android 4.0 (API level 14); please visit +[Android Developers Blog](https://android-developers.googleblog.com/2016/11/google-play-services-and-firebase-for-android-will-support-api-level-14-at-minimum.html) +for more information. -## Demo +## Demo and Releases -Demo applications are available [here](https://akhasoft.github.io/yakhont/yakhont-demo.apk) and -[here (simplified version)](https://akhasoft.github.io/yakhont/yakhont-demo-simple.apk). +Demo applications are available for download from the +[latest release](https://github.com/akhasoft/Yakhont/releases/latest). ## Versions -- _core_: works with native Fragments +- _core_: works with native Android Fragments - _support_: works with support Fragments (android.support.v4.app.Fragment etc.) -- _full_: core + support + debug classes for Activities and Fragments +- _full_: core + support + debug classes for most of Activities and Fragments ## Usage -Add the following to your build.gradle: +Add the following to your build.gradle (you can use **build.gradle** files from [demo](yakhont-demo/buildgradle) +and [simplified demo](yakhont-demo-simple/buildgradle) as working examples). + +1. Update the **buildscript** section: ```groovy buildscript { dependencies { - classpath 'akha.yakhont.weaver:yakhont-weaver:0.9.18' + classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8' + + classpath 'akha.yakhont.weaver:yakhont-weaver:0.9.19' classpath 'org.javassist:javassist:3.20.0-GA' } } +``` + +2. After your **apply plugin: 'com.android.application'** insert the following: + +```groovy +apply plugin: 'com.neenbedankt.android-apt' +``` + +3. Update the **dependencies** section: +```groovy dependencies { - compile 'com.github.akhasoft:yakhont:0.9.18' + compile 'com.google.dagger:dagger:2.10' + apt 'com.google.dagger:dagger-compiler:2.10' + provided 'javax.annotation:jsr250-api:1.0' + + compile 'com.android.support:appcompat-v7:25.3.1' + + compile 'com.github.akhasoft:yakhont:0.9.19' } +``` + +If you're using location API, add the line below: + +```groovy +dependencies { + compile 'com.google.android.gms:play-services-location:11.0.4' +} +``` + +And for the Retrofit2 the following lines are required: +```groovy +dependencies { + compile 'com.squareup.retrofit2:retrofit:2.3.0' + compile 'com.squareup.retrofit2:converter-gson:2.3.0' +} +``` + +4. The code below forced to compile _release_ version only. If you want to compile +the _debug_ version, please replace 'debug' with 'release': + +```groovy +android.variantFilter { variant -> + if (variant.buildType.name == 'debug') { + variant.setIgnore(true); + } +} +``` + +5. The code which runs Yakhont Weaver: + +```groovy String[] weaverConfigFiles = null boolean weaverDebug = false, weaverAddConfig = true android.registerTransform(new akha.yakhont.weaver.WeaverTransform(weaverDebug, android.defaultConfig.applicationId, android.bootClasspath.join(File.pathSeparator), weaverConfigFiles, weaverAddConfig)) ``` -To avoid using the Transform API, you can try the following: +Or (to avoid using the Transform API) you can try the following: ```groovy +String[] weaverConfigFiles = null +boolean weaverDebug = false, weaverAddConfig = true android.applicationVariants.all { variant -> JavaCompile javaCompile = variant.javaCompile javaCompile.doLast { @@ -95,11 +187,11 @@ android.applicationVariants.all { variant -> } ``` -Here the Yakhont weaver manipulates the Java bytecode just compiled, which makes possible +Here the Yakhont Weaver manipulates the Java bytecode just compiled, which makes possible to alternate classes implementation (e.g. add callbacks to Activities and Fragments) without changing their source code. -**Note:** the new Google "Jack and Jill" technology is not supporting bytecode manipulation +**Note:** the Google "Jack and Jill" technology is not supporting bytecode manipulation (at least, for the moment). ## Weaver configuration @@ -116,7 +208,7 @@ automatically appends these directives to your ProGuard configuration. Anyway, it's strongly advised also to keep your model and Retrofit API as follows (it's just an example from the Yakhont Demo, -please update it according to your application's packages names): +so please update it according to your application's packages names): ``` -keep class akha.yakhont.demo.model.** { *; } @@ -133,7 +225,7 @@ $ cd Yakhont $ ./gradlew build ``` -To do a clean build, issue the following commands: +To do a clean build, run the commands below: ``` $ ./gradlew --configure-on-demand yakhont-weaver:clean yakhont-weaver:build diff --git a/yakhont-demo-simple/build.gradle b/yakhont-demo-simple/build.gradle index 04be72d..d1b34b2 100644 --- a/yakhont-demo-simple/build.gradle +++ b/yakhont-demo-simple/build.gradle @@ -22,7 +22,7 @@ buildscript { dependencies { classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8' // Dagger 2 - classpath 'akha.yakhont.weaver:yakhont-weaver:0.9.18' // Yakhont weaver + classpath 'akha.yakhont.weaver:yakhont-weaver:0.9.19' // Yakhont weaver classpath 'org.javassist:javassist:3.20.0-GA' } } @@ -41,8 +41,8 @@ android { minSdkVersion 14 //noinspection OldTargetApi targetSdkVersion 23 // for lower values permissions dialogs will not be shown - versionCode 10000 - versionName '1.0' + versionCode 10101 + versionName '1.1' resConfigs 'en', 'ru' } diff --git a/yakhont-demo/build.gradle b/yakhont-demo/build.gradle index 7b48232..3c120e0 100644 --- a/yakhont-demo/build.gradle +++ b/yakhont-demo/build.gradle @@ -22,7 +22,7 @@ buildscript { dependencies { classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8' // Dagger 2 - classpath 'akha.yakhont.weaver:yakhont-weaver:0.9.18' // Yakhont weaver + classpath 'akha.yakhont.weaver:yakhont-weaver:0.9.19' // Yakhont weaver classpath 'org.javassist:javassist:3.20.0-GA' } } @@ -41,7 +41,7 @@ android { minSdkVersion 14 //noinspection OldTargetApi targetSdkVersion 23 // for lower values permissions dialogs will not be shown - versionCode 10100 + versionCode 10101 versionName '1.1' resConfigs 'en', 'ru' diff --git a/yakhont-weaver/build.gradle b/yakhont-weaver/build.gradle index f033bde..26dbba4 100644 --- a/yakhont-weaver/build.gradle +++ b/yakhont-weaver/build.gradle @@ -18,12 +18,12 @@ apply plugin: 'java' ext { publishedName = 'Yakhont Weaver' - publishedDescription = 'The Yakhont component for the Java bytecode manipulation' + publishedDescription = 'The Yakhont component for working with the Java bytecode' publishedGroupId = 'com.github.akhasoft' publishedArtifactId = 'yakhont-weaver' publishedPackaging = 'jar' - publishedVersion = '0.9.18' + publishedVersion = '0.9.19' projectJavaDocLinks = ['http://jboss-javassist.github.io/javassist/html/', 'http://google.github.io/android-gradle-dsl/javadoc/current/'] diff --git a/yakhont/build.gradle b/yakhont/build.gradle index c91a527..6381408 100644 --- a/yakhont/build.gradle +++ b/yakhont/build.gradle @@ -28,8 +28,8 @@ apply plugin: 'com.neenbedankt.android-apt' apply from: 'preprocessor.gradle' -String verName = '0.9.18' -int verCode = 901818 +String verName = '0.9.19' +int verCode = 901901 ext { publishedName = 'Yakhont'