Daniel Passos danielpassos

Paging/Querying in AeroGear Controller

This document is intended to discuss a solution for AEROGEAR-645 "Add Query/Paging support on RESTful endpoints".
This dev-aerogear mail list thread was used as a starting point to gather requirements and ideas.

Background

Lets just clarify the two concepts that we are dealing with here, Paging and Query.

Paging

Paging deals with limiting the number of results returned from a single request. One "page" can contain a certain number of items as the result of invoking a request, sometimes referred to the size of a page. Let say you want to limit you the number of result returned to 10 items, this could look something like this:

Currently, when creating a new PipeConfig we use a constructor and specify a rootUrl:

    URL rootUrl = new URL("http://todo-aerogear.rhcloud.com/todo-server");

    Pipeline pipeline = new Pipeline(rootUrl);
    PipeConfig config = new PipeConfig(rootUrl, Project.class);

    Pipe<Project> projects = pipeline.pipe(Project.class, config);

Currently, when creating a new PipeConfig we use a constructor and specify a rootUrl:

    URL rootUrl = new URL("http://todo-aerogear.rhcloud.com/todo-server");

    Pipeline pipeline = new Pipeline(rootUrl);
    PipeConfig config = new PipeConfig(rootUrl, Project.class);

    Pipe<Project> projects = pipeline.pipe(Project.class, config);

CDI vs web.xml configuration

To help decide which approach is best for our users this gist will show how configuring CORS in AeroGear Controller would be like using CDI and via web.xml

CDI

For a CDI version and the specific case of CORS users will probably need to provide their own configuration settings. The proposed solution for this is for a user to provide a CDI Producer, for example:

public class CorsConfigProducer {
    public @Produces CorsConfiguration getConfiguration() {
        return CorsConfig.create()
 .enableCorsSupport(true)

AeroGear-iOS 1.0.0.M1

A little bit more than two months ago the work on the AeroGear-iOS library started. We added an initial (and simple) API to communicate against RESTful endpoints. The functionality contains:

HTTP communication
data storage
Authentication and user enrollment

This little document describes the API in a more detailed way.

Not exposing implementation details

Looking at this pull request and the related discussion:

the Pipe interface is the only access that endusers should have to a pipe.
the RestAdapter is a HTTP RESTful implementation of the Pipe.
Endusers should not be able do do new RestAdapter(...);

Looking at the discussion of the above PR, it's clear that there exposing internal APIs and/or implementation details has PROs and CONS...

What is a pipeline ?

A pipeline represents a set of n connections to a server. The pipeline class offers some simple 'management' APIs to work with containing 'pipe' objects. Basically it allows you to add or remove new connections to the pipeline.

What is a pipe ?

A pipe represents one connection to a server. The pipe API is basically an abstraction layer for any server side connection, which all allows you to simply 'read' from, or 'write' to a server connection. However, technical details like RESTful APIs (e.g. HTTP PUT or HTTT GET) are not exposed on the pipeline and pipe APIs. In the future you can have different type of pipe objects (-> connections). The default (and CURRENTLY only supported) type is a REST connection.

Below is an example from our JavaScript lib:

What is a pipeline ?

A pipeline represents a set of n connections to a server. The pipeline class offers some simple 'management' APIs to work with containing 'pipe' objects. Basically it allows you to add or remove new connections to the pipeline.

What is a pipe ?

A pipe represents one connection to a server. The pipe API is basically an abstraction layer for any server side connection, which all allows you to simply 'read' from, or 'write' to a server connection. However, technical details like RESTful APIs (e.g. HTTP PUT or HTTT GET) are not exposed on the pipeline and pipe APIs. In the future you can have different type of pipe objects (-> connections). The default (and CURRENTLY only supported) type is a REST connection.

Below is an example from our JavaScript lib:

Locate the section for your github remote in the .git/config file. It looks like this:

[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
	url = [email protected]:joyent/node.git

Now add the line fetch = +refs/pull/*/head:refs/remotes/origin/pr/* to this section. Obviously, change the github url to match your project's URL. It ends up looking like this:

	#!/bin/sh

	git filter-branch --env-filter '

	an="$GIT_AUTHOR_NAME"
	am="$GIT_AUTHOR_EMAIL"
	cn="$GIT_COMMITTER_NAME"
	cm="$GIT_COMMITTER_EMAIL"

	if [ "$GIT_COMMITTER_EMAIL" = "[email protected]" ]