{"id":15103042,"url":"https://github.com/delight-im/android-ddp","last_synced_at":"2025-04-09T22:15:51.434Z","repository":{"id":23060536,"uuid":"26413916","full_name":"delight-im/Android-DDP","owner":"delight-im","description":"[UNMAINTAINED] Meteor's Distributed Data Protocol (DDP) for clients on Android","archived":false,"fork":false,"pushed_at":"2018-07-12T16:32:49.000Z","size":3775,"stargazers_count":274,"open_issues_count":22,"forks_count":53,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-09T22:15:45.637Z","etag":null,"topics":["android","android-ddp","client","database","ddp","java","meteor","real-time","realtime"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/delight-im.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-11-10T00:03:30.000Z","updated_at":"2024-09-06T09:53:09.000Z","dependencies_parsed_at":"2022-08-21T10:10:58.103Z","dependency_job_id":null,"html_url":"https://github.com/delight-im/Android-DDP","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/delight-im%2FAndroid-DDP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/delight-im%2FAndroid-DDP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/delight-im%2FAndroid-DDP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/delight-im%2FAndroid-DDP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/delight-im","download_url":"https://codeload.github.com/delight-im/Android-DDP/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119288,"owners_count":21050755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-ddp","client","database","ddp","java","meteor","real-time","realtime"],"created_at":"2024-09-25T19:20:21.199Z","updated_at":"2025-04-09T22:15:51.408Z","avatar_url":"https://github.com/delight-im.png","language":"Java","readme":"# Android-DDP\n\nThis library implements the [Distributed Data Protocol](https://www.meteor.com/ddp) (DDP) from Meteor for clients on Android.\n\nConnect your native Android apps, written in Java, to apps built with the [Meteor](https://www.meteor.com/) framework and build real-time features.\n\n## Motivation\n\n * Have you built a web application with Meteor?\n   * Using this library, you can build native Android apps that can talk to your Meteor server and web application.\n * Are you primarily an Android developer (who has never heard of Meteor)?\n   * With \"Android-DDP\", you can use a Meteor server as your backend for real-time applications on Android.\n * Doesn't Meteor provide built-in features for Android app development already?\n   * With Meteor's built-in features, your Android app will be written in HTML, CSS and JavaScript, wrapped in a `WebView`. It will not be a *native* app.\n   * By using this library, however, you can write native Android apps in Java while still using Meteor as your real-time backend.\n\n## Requirements\n\n * Android 2.3+\n\n## Installation\n\n * Add this library to your project\n   * Declare the Gradle repository in your root `build.gradle`\n\n     ```gradle\n     allprojects {\n         repositories {\n             maven { url \"https://jitpack.io\" }\n         }\n     }\n     ```\n\n   * Declare the Gradle dependency in your app module's `build.gradle`\n\n     ```gradle\n     dependencies {\n         compile 'com.github.delight-im:Android-DDP:v3.3.1'\n     }\n     ```\n\n * Add the Internet permission to your app's `AndroidManifest.xml`:\n\n    ```xml\n    \u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n    ```\n\n## Usage\n\n * Creating a new instance of the DDP client\n\n   ```java\n   public class MyActivity extends Activity implements MeteorCallback {\n\n       private Meteor mMeteor;\n\n       @Override\n       protected void onCreate(Bundle savedInstanceState) {\n           super.onCreate(savedInstanceState);\n\n           // ...\n\n           // create a new instance\n           mMeteor = new Meteor(this, \"ws://example.meteor.com/websocket\");\n\n           // register the callback that will handle events and receive messages\n           mMeteor.addCallback(this);\n\n           // establish the connection\n           mMeteor.connect();\n       }\n\n       public void onConnect(boolean signedInAutomatically) { }\n\n       public void onDisconnect() { }\n\n       public void onDataAdded(String collectionName, String documentID, String newValuesJson) {\n           // parse the JSON and manage the data yourself (not recommended)\n           // or\n           // enable a database (see section \"Using databases to manage data\") (recommended)\n       }\n\n       public void onDataChanged(String collectionName, String documentID, String updatedValuesJson, String removedValuesJson) {\n           // parse the JSON and manage the data yourself (not recommended)\n           // or\n           // enable a database (see section \"Using databases to manage data\") (recommended)\n       }\n\n       public void onDataRemoved(String collectionName, String documentID) {\n           // parse the JSON and manage the data yourself (not recommended)\n           // or\n           // enable a database (see section \"Using databases to manage data\") (recommended)\n       }\n\n       public void onException(Exception e) { }\n\n       @Override\n       public void onDestroy() {\n           mMeteor.disconnect();\n           mMeteor.removeCallback(this);\n           // or\n           // mMeteor.removeCallbacks();\n\n           // ...\n\n           super.onDestroy();\n       }\n\n   }\n   ```\n\n * Singleton access\n   * Creating an instance at the beginning\n\n     ```java\n     MeteorSingleton.createInstance(this, \"ws://example.meteor.com/websocket\")\n     // instead of\n     // new Meteor(this, \"ws://example.meteor.com/websocket\")\n     ```\n\n   * Accessing the instance afterwards (across `Activity` instances)\n\n     ```java\n     MeteorSingleton.getInstance()\n     // instead of\n     // mMeteor\n     ```\n\n   * All other API methods can be called on `MeteorSingleton.getInstance()` just as you would do on any other `Meteor` instance, as documented here with `mMeteor`\n\n * Registering a callback\n\n   ```java\n   // MeteorCallback callback;\n   mMeteor.addCallback(callback);\n   ```\n\n * Unregistering a callback\n\n   ```java\n   mMeteor.removeCallbacks();\n   // or\n   // // MeteorCallback callback;\n   // mMeteor.removeCallback(callback);\n   ```\n\n * Available data types\n\n   | JavaScript / JSON                                          | Java / Android                                                                                                                                                        |\n   | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n   | **`String`** (e.g. `\"John\"` or `'Jane'`)                   | **`String`** (e.g. `\"John\"` or `\"Jane\"`)                                                                                                                              |\n   | **`Number`** (e.g. `42`)                                   | **`byte`** (e.g. `(byte) 42`)                                                                                                                                         |\n   |                                                            | **`short`** (e.g. `(short) 42`)                                                                                                                                       |\n   |                                                            | **`int`** (e.g. `42`)                                                                                                                                                 |\n   |                                                            | **`long`** (e.g. `42L`)                                                                                                                                               |\n   |                                                            | **`float`** (e.g. `3.14f`)                                                                                                                                            |\n   |                                                            | **`double`** (e.g. `3.14`)                                                                                                                                            |\n   | **`Boolean`** (e.g. `true`)                                | **`boolean`** (e.g. `true`)                                                                                                                                           |\n   | **`Array`** (e.g. `[ 7, \"Hi\", true ]`)                     | **`Object[]`** (e.g. `new Object[] { 7, \"Hi\", true }`)                                                                                                                |\n   |                                                            | **`List\u003cObject\u003e`** (e.g. `List\u003cObject\u003e list = new LinkedList\u003cObject\u003e(); list.add(7); list.add(\"Hi\"); list.add(true);`)                                                |\n   | **`Object`** (e.g. `{ \"amount\": 100, \"currency\": \"USD\" }`) | **`Map\u003cString, Object\u003e`** (e.g. `Map\u003cString, Object\u003e map = new HashMap\u003cString, Object\u003e(); map.put(\"amount\", 100); map.put(\"currency\", \"USD\");`)                       |\n   |                                                            | **`MyClass`** (e.g. `public class MyClass { public int amount; public String currency; } MyClass myObj = new MyClass(); myObj.amount = 100; myObj.currency = \"USD\";`) |\n   | `null`                                                     | `null`                                                                                                                                                                |\n\n * Inserting data into a collection\n\n   ```java\n   Map\u003cString, Object\u003e values = new HashMap\u003cString, Object\u003e();\n   values.put(\"_id\", \"my-id\");\n   values.put(\"some-key\", \"some-value\");\n\n   mMeteor.insert(\"my-collection\", values);\n   // or\n   // mMeteor.insert(\"my-collection\", values, new ResultListener() { });\n   ```\n\n * Updating data in a collection\n\n   ```java\n   Map\u003cString, Object\u003e query = new HashMap\u003cString, Object\u003e();\n   query.put(\"_id\", \"my-id\");\n\n   Map\u003cString, Object\u003e values = new HashMap\u003cString, Object\u003e();\n   values.put(\"some-key\", \"some-value\");\n\n   mMeteor.update(\"my-collection\", query, values);\n   // or\n   // mMeteor.update(\"my-collection\", query, values, options);\n   // or\n   // mMeteor.update(\"my-collection\", query, values, options, new ResultListener() { });\n   ```\n\n * Deleting data from a collection\n\n   ```java\n   mMeteor.remove(\"my-collection\", \"my-id\");\n   // or\n   // mMeteor.remove(\"my-collection\", \"my-id\", new ResultListener() { });\n   ```\n\n * Subscribing to data from the server\n\n   ```java\n   String subscriptionId = mMeteor.subscribe(\"my-subscription\");\n   // or\n   // String subscriptionId = mMeteor.subscribe(\"my-subscription\", new Object[] { arg1, arg2 });\n   // or\n   // String subscriptionId = mMeteor.subscribe(\"my-subscription\", new Object[] { arg1, arg2 }, new SubscribeListener() { });\n   ```\n\n * Unsubscribing from a previously established subscription\n\n   ```java\n   mMeteor.unsubscribe(subscriptionId);\n   // or\n   // mMeteor.unsubscribe(subscriptionId, new UnsubscribeListener() { });\n   ```\n\n * Calling a custom method defined on the server\n\n   ```java\n   mMeteor.call(\"myMethod\");\n   // or\n   // mMeteor.call(\"myMethod\", new Object[] { arg1, arg2 });\n   // or\n   // mMeteor.call(\"myMethod\", new ResultListener() { });\n   // or\n   // mMeteor.call(\"myMethod\", new Object[] { arg1, arg2 }, new ResultListener() { });\n   ```\n\n * Disconnect from the server\n\n   ```java\n   mMeteor.disconnect();\n   ```\n\n * Creating a new account (requires `accounts-password` package)\n\n   ```java\n   mMeteor.registerAndLogin(\"john\", \"john.doe@example.com\", \"password\", new ResultListener() { });\n   // or\n   // mMeteor.registerAndLogin(\"john\", \"john.doe@example.com\", \"password\", profile, new ResultListener() { });\n   ```\n\n * Signing in with an existing username (requires `accounts-password` package)\n\n   ```java\n   mMeteor.loginWithUsername(\"john\", \"password\", new ResultListener() { });\n   ```\n\n * Signing in with an existing email address (requires `accounts-password` package)\n\n   ```java\n   mMeteor.loginWithEmail(\"john.doe@example.com\", \"password\", new ResultListener() { });\n   ```\n\n * Check if the client is currently logged in (requires `accounts-password` package)\n\n   ```java\n   mMeteor.isLoggedIn();\n   ```\n\n * Get the client's user ID (if currently logged in) (requires `accounts-password` package)\n\n   ```java\n   mMeteor.getUserId();\n   ```\n\n * Logging out (requires `accounts-password` package)\n\n   ```java\n   mMeteor.logout();\n   // or\n   // mMeteor.logout(new ResultListener() { });\n   ```\n\n * Checking whether the client is connected\n\n   ```java\n   mMeteor.isConnected();\n   ```\n\n * Manually attempt to re-connect (if necessary)\n\n   ```java\n   mMeteor.reconnect();\n   ```\n\n## Using databases to manage data\n\n### Enabling a database\n\nPass an instance of `Database` to the constructor. Right now, the only subclass provided as a built-in database is `InMemoryDatabase`. So the code for the constructor becomes:\n\n```java\nmMeteor = new Meteor(this, \"ws://example.meteor.com/websocket\", new InMemoryDatabase());\n```\n\nAfter that change, all data received from the server will automatically be parsed, updated and managed for you in the built-in database. That means no manual JSON parsing!\n\nSo whenever you receive data notifications via `onDataAdded`, `onDataChanged` or `onDataRemoved`, that data has already been merged into the database and can be retrieved from there. In these callbacks, you can thus ignore the parameters containing JSON data and instead get the data from your database.\n\n### Accessing the database\n\n```java\nDatabase database = mMeteor.getDatabase();\n```\n\nThis method call and most of the following method calls can be chained for simplicity.\n\n### Getting a collection from the database by name\n\n```java\n// String collectionName = \"myCollection\";\nCollection collection = mMeteor.getDatabase().getCollection(collectionName);\n```\n\n### Retrieving the names of all collections from the database\n\n```java\nString[] collectionNames = mMeteor.getDatabase().getCollectionNames();\n```\n\n### Fetching the number of collections from the database\n\n```java\nint numCollections = mMeteor.getDatabase().count();\n```\n\n### Getting a document from a collection by ID\n\n```java\n// String documentId = \"wjQvNQ6sGjzLMDyiJ\";\nDocument document = mMeteor.getDatabase().getCollection(collectionName).getDocument(documentId);\n```\n\n### Retrieving the IDs of all documents from a collection\n\n```java\nString[] documentIds = mMeteor.getDatabase().getCollection(collectionName).getDocumentIds();\n```\n\n### Fetching the number of documents from a collection\n\n```java\nint numDocuments = mMeteor.getDatabase().getCollection(collectionName).count();\n```\n\n### Querying a collection for documents\n\nAny of the following method calls can be chained and combined in any way to select documents via complex queries.\n\n```java\n// String fieldName = \"age\";\n// int fieldValue = 62;\nQuery query = mMeteor.getDatabase().getCollection(collectionName).whereEqual(fieldName, fieldValue);\n```\n\n```java\n// String fieldName = \"active\";\n// int fieldValue = false;\nQuery query = mMeteor.getDatabase().getCollection(collectionName).whereNotEqual(fieldName, fieldValue);\n```\n\n```java\n// String fieldName = \"accountBalance\";\n// float fieldValue = 100000.00f;\nQuery query = mMeteor.getDatabase().getCollection(collectionName).whereLessThan(fieldName, fieldValue);\n```\n\n```java\n// String fieldName = \"numChildren\";\n// long fieldValue = 3L;\nQuery query = mMeteor.getDatabase().getCollection(collectionName).whereLessThanOrEqual(fieldName, fieldValue);\n```\n\n```java\n// String fieldName = \"revenue\";\n// double fieldValue = 0.00;\nQuery query = mMeteor.getDatabase().getCollection(collectionName).whereGreaterThan(fieldName, fieldValue);\n```\n\n```java\n// String fieldName = \"age\";\n// int fieldValue = 21;\nQuery query = mMeteor.getDatabase().getCollection(collectionName).whereGreaterThanOrEqual(fieldName, fieldValue);\n```\n\n```java\n// String fieldName = \"address\";\nQuery query = mMeteor.getDatabase().getCollection(collectionName).whereNull(fieldName);\n```\n\n```java\n// String fieldName = \"modifiedAt\";\nQuery query = mMeteor.getDatabase().getCollection(collectionName).whereNotNull(fieldName);\n```\n\n```java\n// String fieldName = \"age\";\n// Integer[] fieldValues = new Integer[] { 60, 70, 80 };\nQuery query = mMeteor.getDatabase().getCollection(collectionName).whereIn(fieldName, fieldValues);\n```\n\n```java\n// String fieldName = \"languageCode\";\n// String[] fieldValues = new String[] { \"zh\", \"es\", \"en\", \"hi\", \"ar\" };\nQuery query = mMeteor.getDatabase().getCollection(collectionName).whereNotIn(fieldName, fieldValues);\n```\n\nAny query can be executed by a `find` or `findOne` call. The step of first creating the `Query` instance can be skipped if you chain the calls to execute the query immediately.\n\n```java\nDocument[] documents = mMeteor.getDatabase().getCollection(collectionName).find();\n```\n\n```java\n// int limit = 30;\nDocument[] documents = mMeteor.getDatabase().getCollection(collectionName).find(limit);\n```\n\n```java\n// int limit = 30;\n// int offset = 5;\nDocument[] documents = mMeteor.getDatabase().getCollection(collectionName).find(limit, offset);\n```\n\n```java\nDocument document = mMeteor.getDatabase().getCollection(collectionName).findOne();\n```\n\nChained together, these calls may look as follows, for example:\n\n```java\nDocument document = mMeteor.getDatabase().getCollection(\"users\").whereNotNull(\"lastLoginAt\").whereGreaterThan(\"level\", 3).findOne();\n```\n\n### Getting a field from a document by name\n\n```java\n// String fieldName = \"age\";\nObject field = mMeteor.getDatabase().getCollection(collectionName).getDocument(documentId).getField(fieldName);\n```\n\n### Retrieving the names of all fields from a document\n\n```java\nString[] fieldNames = mMeteor.getDatabase().getCollection(collectionName).getDocument(documentId).getFieldNames();\n```\n\n### Fetching the number of fields from a document\n\n```java\nint numFields = mMeteor.getDatabase().getCollection(collectionName).getDocument(documentId).count();\n```\n\n## Contributing\n\nAll contributions are welcome! If you wish to contribute, please create an issue first so that your feature, problem or question can be discussed.\n\n## Dependencies\n\n * [nv-websocket-client](https://github.com/TakahikoKawasaki/nv-websocket-client) — [Takahiko Kawasaki](https://github.com/TakahikoKawasaki) — [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)\n * [Jackson Core](https://github.com/FasterXML/jackson-core) — [FasterXML](https://github.com/FasterXML) — [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)\n * [Jackson ObjectMapper](https://github.com/FasterXML/jackson-databind) — [FasterXML](https://github.com/FasterXML) — [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)\n\n## Further reading\n\n * [DDP — Specification](https://github.com/meteor/meteor/blob/devel/packages/ddp/DDP.md)\n * [Jackson — Documentation](http://wiki.fasterxml.com/JacksonDocumentation)\n\n## Disclaimer\n\nThis project is neither affiliated with nor endorsed by Meteor.\n\n## License\n\n```\nCopyright (c) delight.im \u003cinfo@delight.im\u003e\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n  http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdelight-im%2Fandroid-ddp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdelight-im%2Fandroid-ddp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdelight-im%2Fandroid-ddp/lists"}