This library is a port of Parse's REST API to CodenameOne (and by extension to Java).
Java Other
Latest commit f70304d Oct 31, 2016 @sidiabale committed on GitHub Merge pull request #25 from ahmedengu/fetchIfNeeded
PO: fetchIfNeeded() getEndPoint to getClassName

README.md

Build Status (master): Build Status (master)

Build Status (develop): Build Status (develop)

Tests are run with the following backend configurations:

  • Parse.com
  • Parse Server version 2.2.13 hosted on openshift

Parse4CN1 - Codename One Library for Parse.com and Parse Server

This library is a port of Parse's REST API to CodenameOne (and by extension to Java).

Synopsis

The Parse platform provides a complete backend solution for your mobile application. Parse provides a REST API as well as libraries for different mobile platforms like Android and iOS. CodenameOne (CN1 for short) on the other hand is a great framework for cross-platform mobile application development. Although some of the functionality provided by Parse is offered to paying CN1 users, integration of third-party libraries is allowed and even encouraged in CN1. This project aims at making the Parse platform available to CN1 apps thereby giving developers more options for cloud-based backend solutions in CN1. In order to maximize platform support, this library aims at implementing the REST API specification rather than, for instance, integrating the existing Parse native libraries for various platforms to achieve the same functionality. Of course, where possible, advanced features that go beyond the REST API (e.g., background operations) will also be supported by this library preferably in a generic manner.

Since CN1 is written in Java, this library can also be used in pure Java projects as illustrated here.

On January 28th 2016, Parse.com announced that the service will be retired on January 28th 2017. Accordingly, parse4cn1 has been updated to support the open source Parse Server.

License

Apache License, Version 2.0

Requirements

  1. Codename One 1.0 or higher (tested with the CN1 Netbeans plugin but should work with others)
  2. CN1JSON library (delivered along with this library for compatibility; see the Installation section below)

Installation

Automatic Installation

CodenameOne recently announced automatic installation and distribution of cn1libs. parse4cn1 can be installed by following the instructions outlined here. Note, however, that as at June 2016, cn1libs distributed via this process are manually deployed. This means that you might not immediately see the latest version of parse4cn1 until after a few days. In that case, you can revert to manual installation as described next.

Manual Installation

  1. Download the dist/parse4cn1.cn1lib and dist/CN1JSON.cn1lib files and copy them into your Codename One Application's "lib" directory (or alternatively, use the corresponding JARs in dist/parse4cn1.jar and dist/lib/CN1JSON.jar).

    Note that it is highly recommended to use well-defined releases instead of pulling files from the master or develop branch.

  2. Refresh project libs, if applicable, for the added cn1libs to be picked up (e.g. by right-click on your application's icon in the project explorer, and selecting "Codename One" >> "Refresh cn1lib files" in Netbeans or "CodenameOne" >> "Refresh Libs" in Eclipse).

Coverage

The Parse REST API is quite extensive. As such, we maintain an overview of the functionality that is currently covered. Developers are most welcome to work on pending functionality. Note that some of the functionality marked as pending below may actually be present in the source code inherited from Parse4J. However, the status here reflects what has been tested and verified to work with CN1. Any functionality not marked as implemented below may be used at own risk :)

API Status Remarks
Objects IMPLEMENTED
Queries IMPLEMENTED
Users IMPLEMENTED Still pending: (1) Linking users (Facebook, Twitter, etc.) (2) Security (ACLs)
Sessions Pending
Roles Pending
Files IMPLEMENTED
Analytics Pending
Config IMPLEMENTED
Push Notifications* Implemented for Parse.com but pending for Parse Server
Installations Implemented for Parse.com but pending for Parse Server
Cloud Code IMPLEMENTED
GeoPoints IMPLEMENTED

*Advanced feature that cannot be realized using REST API only; involves native code integration. See the CN1 Parse push guide for more details.

Advanced Features Remarks
Serialization Realized via CN1's Externalizable interface. See example here
User-defined ParseObject subclasses See example here

Release Planning

Unscheduled (read: Feel free to contribute!)

  • Installations and push notification support for Parse Server (if you're interested in this functionality in the short term, kindly fill the short survey at the end of this blog post)
  • Analytics
  • Roles
  • Sessions
  • Linking users
  • Background operations (e.g. saving, fetching)
  • Pinning items (offline mode)
  • Expose cloud modules like Twilio and Mailgun via cloud code

Parse Server Known Issues

Parse Server is actively in development. As such, there are bugs/missing features, etc. The following is a list of some known issues and their implications for parse4cn1. A more comprehensive list of issues can be found in the issue tracker of the Parse Server Github repository. See also the known incompatibilities of Parse Server w.r.t parse.com as outlined here.

Issue Type Implications
Files and GeoPoints are not correctly saved in ParseConfig (see this issue) Bug Creating ParseConfig objects of type File or GeoPoint using the affected Parse Server versions will not work as expected. Also, the parse4cn1 ParseConfigTest will fail when run against a backend in which the ParseConfig test objects were initialized using any of the affected Parse Server versions
Master key is required for retrieving installations Change w.r.t. Parse.com Since parse4cn1 does not support any operations requiring the master key, retrieving installations is now realized via cloud code (see this comment)
Master key is required for sending push notifications from clients (see this page) Change w.r.t. Parse.com Since parse4cn1 does not support any operations requiring the master key, client-triggered push notifications will have to be realized via cloud code
Queries in ParseCloud functions that relate to a specific user must now include the user's session token. More info on this change is documented here Change w.r.t. Parse.com Session token header must be explicitly added to the post request as illustrated here.

Usage Examples

See Usage examples

Contributing

Contributing to this project is most welcome; the more, the merrier! Simply fork the master branch, implement a feature / bug fix and initiate a pull request. Please bear the following in mind though to ensure smooth and timely integration of your changes:

  1. The public interface of this API is as much as possible aligned to the official Parse Android SDK. When implementing functionality already present there, please try to use the same method names and structure where possible. This just makes it consistent and easier to follow.

    Of course, there may be cases where you really think a different name for a given functionality or different semantics for the same method name are much better. That's fine. Just try to make the deviations clear in the method documentation, which leads me to the next point.

  2. Document at least all public facing methods with comments that add value (not simply boilerplate comments that state the obvious).

  3. Write tests for added functionality (see the test directory for some inspiration if needed).

  4. Make sure all tests are passing at least in the Java test application (run on travis) but preferably also in the CN1 test app before issuing a pull request.

Furthermore, it's handy, at the time you pick up a feature, to mention it so that others can see what's in progress and efforts can be consolidated (there's little or no value in having multiple implementations of the same feature going on in parallel). So update the coverage table above with what you're working on as well as an estimate of when you expect it to be done. If you can't update this page directly, just create a ticket with the information and this page will be updated for you. Thanks!

Credits

  1. Thiago Locatelli's Parse4J project (version 1.3) from which the initial design and implementation of Parse4CN1 were adapted.
  2. Steve Hannah's CN1JSON library.