Starter guide

You wanna see what RoboSpice looks like in action ? Great ! This is the page you are looking for.

RoboSpice usage

Setting up your project

• Setup for Maven users
• Setup for Non-Maven users

Using RoboSpice

To use RoboSpice in your application, there are 4 steps :

• 1 has to be performed once for all requests (creating a SpiceService) ;
• 1 has to be done for every Activity class (or only once for your project if you use a common base class for all your activities) ;
• and 2 steps have to be repeated for each requests (creating a request and a listener).

The snippets below have been extracted from the Json Tweeter example of Robospice Motivations app.

Create a SpiceService

This part is the most difficult, but you only have to do it once to enable all requests to be processed. You will define a subclass of SpiceService and declare it in the AndroidManifest.xml file.

public class TweeterJsonSpiceService extends SpringAndroidContentService {

    @Override
    public CacheManager createCacheManager( Application application ) {
        CacheManager cacheManager = new CacheManager();

        InFileStringObjectPersister inFileStringObjectPersister = new InFileStringObjectPersister( application );
        InFileInputStreamObjectPersister inFileInputStreamObjectPersister = new InFileInputStreamObjectPersister( application );
        JacksonObjectPersisterFactory inJSonFileObjectPersisterFactory = new JacksonObjectPersisterFactory( application );

        inFileStringObjectPersister.setAsyncSaveEnabled( true );
        inFileInputStreamObjectPersister.setAsyncSaveEnabled( true );
        inJSonFileObjectPersisterFactory.setAsyncSaveEnabled( true );

        cacheManager.addPersister( inFileStringObjectPersister );
        cacheManager.addPersister( inFileInputStreamObjectPersister );
        cacheManager.addPersister( inJSonFileObjectPersisterFactory );
        return cacheManager;
    }

    @Override
    public RestTemplate createRestTemplate() {
        RestTemplate restTemplate = new RestTemplate();
        //find more complete examples in RoboSpice Motivation app
        //to enable Gzip compression and setting request timeouts.

        // web services support json responses
        MappingJacksonHttpMessageConverter jsonConverter = new MappingJacksonHttpMessageConverter();
        FormHttpMessageConverter formHttpMessageConverter = new FormHttpMessageConverter();
        StringHttpMessageConverter stringHttpMessageConverter = new StringHttpMessageConverter();
        final List< HttpMessageConverter< ? >> listHttpMessageConverters = restTemplate.getMessageConverters();

        listHttpMessageConverters.add( jsonConverter );
        listHttpMessageConverters.add( formHttpMessageConverter );
        listHttpMessageConverters.add( stringHttpMessageConverter );
        restTemplate.setMessageConverters( listHttpMessageConverters );
        return restTemplate;
    }

Then add this to your AndroidManifest.xml file :

        <service
            android:name=".robospice.tweeter.json.TweeterJsonSpiceService"
            android:exported="false" />

Spice your activity

In your activity, or a base class if you use one (preferred), add the following :

    private static final String JSON_CACHE_KEY = "tweets_json";
    private SpiceManager spiceManager = new SpiceManager( TweeterJsonSpiceService.class );

    @Override
    protected void onStart() {
        super.onStart();
        spiceManager.start( this );
    }

    @Override
    protected void onStop() {
        spiceManager.shouldStop();
        super.onStop();
    }

    public void refreshTweets() {
        spiceManager.execute( new TweetJsonRequest(), JSON_CACHE_KEY, DurationInMillis.NEVER, new TweetRequestListener() );
    }

In the example above, you can see that the third argument passed to the execute() method is the constant DurationInMillis.NEVER. You use this parameter to specify when data will be taken from the cache without invoking retrieval of new data from the network.

If you pass a long value, then it represents the maximum age in milliseconds of cached data that a SpiceManager will accept.

The constant DurationInMillis.ALWAYS used in the above example indicates that the client never considers a data in cache as expired, regardless of how recent it is. Data in cache will always be returned, a network call will only be made once.

There is also a constant named DurationInMillis.NEVER which means that the data in cache will always be considered expired, regardless of how recent it is. Thus, the SpiceRequest will always perform a network call, and you will never get the data in cache.

There are also constants that represent specific time durations, such as DurationInMillis.ONE_HOUR and DurationInMillis.ONE_WEEK provided as helpers to write durations in milliseconds.

Create a request and a listener

You will repeat this step for each different kind of request. Those steps are easy and intuitive :

public class TweetJsonRequest extends RestContentRequest< ListTweets > {

    public TweetJsonRequest() {
        super( ListTweets.class );
    }

    @Override
    public ListTweets loadDataFromNetwork() throws Exception {
        return getRestTemplate().getForObject( "http://search.twitter.com/search.json?q=android&rpp=20", ListTweets.class );
    }
}

As an inner class of your activity, add a RequestlListener that will update your UI. Don't worry about memory leaks, RoboSpice manages your activity life cycle.

private class TweetRequestListener implements RequestListener< ListTweets > {

        @Override
        public void onRequestFailure( SpiceException arg0 ) {
          //update your UI
        }

        @Override
        public void onRequestSuccess( ListTweets listTweets ) {
          //update your UI
        }
    }

###POJO classes

In this example, we used the following POJOs to receive a list of Tweets using Json via Jackson :

@JsonIgnoreProperties(ignoreUnknown = true)
public class ListTweets {

    private List< Tweet > results;

    public List< Tweet > getResults() {
        return results;
    }

    public void setResults( List< Tweet > results ) {
        this.results = results;
    }
}

@JsonIgnoreProperties(ignoreUnknown = true)
public class Tweet {
    private String text;

    public String getText() {
        return text;
    }

    public void setText( String text ) {
        this.text = text;
    }
}

You're done ! Launch your activity, plug the refreshTweets() method to a Button for instance, and enjoy !