ANN: Couchbase Lite Android Project Restructure

[Traun Leyden]

Couchbase Lite Android has been restructured to allow for a clear split between code that has Android API dependencies and code that can run on non-Android platforms (aka "Portable Java").

Here is a diagram that visually shows the transition.

The new project structure is more fully documented on a wiki page.

Important Changes

1)  couchbase-lite-android-core renamed to couchbase-lite-java-core

What was previously named couchbase-lite-android-core has been renamed to couchbase-lite-java-core.  The bulk of the code remains here, with all Android API dependencies removed.

2) couchbase-lite-android-liteserv plays the role that couchbase-lite-android used to play

Previously, there were two "wrapper" projects that included all of the Couchbase Lite modules:

https://github.com/couchbase/couchbase-lite-android/

https://github.com/couchbaselabs/LiteServAndroid

As described in the next bullet point, couchbase-lite-android has a much tighter scope now, and now no longer serves as a wrapper project.

LiteServAndroid has been renamed to coubhase-lite-android-liteserv and functions as the single "wrapper project" example -- eg, a project that includes all of the Couchbase Lite modules.

3) couchbase-lite-android has a much tighter scope now.

Before: The couchbase-lite-android repository used to be a "wrapper" project that included the three core Couchbase Lite modules (core, listener, and javascript). 

After: This repo that wraps the java core and provides the dependencies on the Android API, eg. the Android SQLite Storage Engine.  It also contains all the unit test code.  It no longer includes the listener or javascript dependencies.

In a typical app, this is the repo that you would likely want to depend on.  Eg, GrocerySync has a dependency on this repo.

4) Renamed repositories: 

    couchbase-lite-android-listener -> couchbase-lite-java-listener

    couchbase-lite-android-javascript -> couchbase-lite-java-javascript

These repositories did not have a huge amount of changes, aside from being renamed and changed to remove all direct dependencies on Android API's.

Also couchbase-lite-java-listener is now packaged into a maven artifact.

5) Maven artifacts have been renamed, changed group ID

The new maven artifact id's:

'com.couchbase.lite:java-core:$version'

'com.couchbase.lite:android:$version'

'com.couchbase.lite:java-listener:$version'

'com.couchbase.lite:java-javascript:$version'

When there is another release, it will use these maven artifact id's.  In the meantime, there is no need to update your maven artifact references.

6) Submodule dependencies are now in the "libraries" directory

In projects that include submodule dependencies, the dependencies are now grouped under the "libraries" directory to better match the best practices for organizing gradle projects.

7) A "Portable Java" project stub has been added

couchbase-lite-java is currently a stub project, but will eventually be the core module for a portable java version of Couchbase Lite.  Android devs can ignore this module.

Action items you should take as a developer

1) Update submodules + git repo URLS

Update any submodule / git repo pointers from:

couchbase-lite-android-core -> couchbase-lite-android

couchbase-lite-android-listener -> couchbase-lite-java-listener

couchbase-lite-android-javascript -> couchbase-lite-java-javascript

2) Explode dependencies on couchbase-lite-android-core

If you had a submodule dependency on couchbase-lite-android-core, you will need to "explode" this into two submodule dependencies:

couchbase-lite-android

couchbase-lite-java-core

To see an example of this in action, see the latest master branch of GrocerySync.   Another example can be seen by looking at the couchbase-lite-android-liteserv repo.

3) Clone the couchbase-lite-android from scratch

A "force push" was done on couchbase-lite-android repo, which caused much of it's history to be re-written.  If you have the couchbase-lite-android repo cloned, rather than trying to do a "git pull" on this repo, you'll want to just completely clone it from scratch.

I think that's it.   Hopefully this will be a positive and non-disruptive change for everyone.

[Matt Quinn]

On Mon, Feb 10, 2014 at 04:26:35PM -0800, Traun Leyden wrote:
> Couchbase Lite Android has been restructured to allow for a clear split
> between code that has Android API dependencies and code that can run on
> non-Android platforms (aka "Portable Java").

Awesome! Thanks Traun. It was straightforward to get the new
configuration set up for hacking. I'm going to move our app over
tomorrow; hopefully it's as straightforward.

Although, I notice that couchbase-lite-android-ektorp hasn't been
updated with the new structure yet. If no one's gotten to it, I'll have
to take a crack at that tomorrow. (I know CBL+Ektorp has been
deprecated, and we are working to migrate off it, but we aren't all the
way there yet).

> *3) couchbase-lite-android has a much tighter scope now.*
>
> [...]

>
> After: This repo that wraps the java core and provides the dependencies on
> the Android API, eg. the Android SQLite Storage Engine. It also contains
> all the unit test code.

One minor inconvenience I've stumbled on just now is that, with the unit
tests separated from the code, changes that touch both the code and the
tests require two pull requests (one to each project). I can't picture
how the alternative (tests in core) would even run though, so I'm not
really advocating anything. Just a note.

On the plus side, it will definitely mean that test commits and bug-fix
commits are separated out for review :)

[Traun Leyden]

Although, I notice that couchbase-lite-android-ektorp hasn't been
updated with the new structure yet. If no one's gotten to it, I'll have
to take a crack at that tomorrow. (I know CBL+Ektorp has been
deprecated, and we are working to migrate off it, but we aren't all the
way there yet).

Yes that would be great!  If you run into any issues don't hesitate to ask.  

 

One minor inconvenience I've stumbled on just now is that, with the unit
tests separated from the code, changes that touch both the code and the
tests require two pull requests (one to each project). I can't picture
how the alternative (tests in core) would even run though, so I'm not
really advocating anything. Just a note.

Yeah, it's a little awkward.  I banged my head on it for quite a while, trying to get the unit tests to live in couchbase-lite-java-core, but they weren't picking up the storage engine when the tests were running, and so I ended up punting on this and will try to tackle it in another pass.