JRAW-Android

This is an extension to the Java Reddit API Wrapper that adds some Android-specific classes.

Getting Started

repositories {
    jcenter()
}

dependencies {
    // If you include JRAW-Android, you don't need to also include JRAW.
    implementation 'net.dean.jraw:JRAW-Android:1.0.0'
}

Before using this library it is highly recommended that you first read the OAuth2 page in the JRAW documentation.

First create a reddit OAuth2 app here. Note the client ID and redirect URL, you'll need these later.

Add these <meta-data> keys to your manifest:

<application>
    ...
    <meta-data
        android:name="net.dean.jraw.android.REDDIT_USERNAME"
        android:value="(...)" />
    <meta-data
        android:name="net.dean.jraw.android.CLIENT_ID"
        android:value="(...)" />
    <meta-data
        android:name="net.dean.jraw.android.REDIRECT_URL"
        android:value="(...)" />
</application>

The REDDIT_USERNAME key is used to create a UserAgent for your app. See here for more details.

Create your Application class:

public final class App extends Application {
    private static AccountHelper accountHelper;
    private static SharedPreferencesTokenStore tokenStore;

    @Override
    public void onCreate() {
        super.onCreate();

        // Get UserAgent and OAuth2 data from AndroidManifest.xml
        AppInfoProvider provider = new ManifestAppInfoProvider(getApplicationContext());

        // Ideally, this should be unique to every device
        UUID deviceUuid = UUID.randomUUID();

        // Store our access tokens and refresh tokens in shared preferences
        tokenStore = new SharedPreferencesTokenStore(getApplicationContext());
        // Load stored tokens into memory
        tokenStore.load();
        // Automatically save new tokens as they arrive
        tokenStore.setAutoPersist(true);

        // An AccountHelper manages switching between accounts and into/out of userless mode.
        accountHelper = AndroidHelper.accountHelper(provider, deviceUuid, tokenStore);

        // Every time we use the AccountHelper to switch between accounts (from one account to
        // another, or into/out of userless mode), call this function
        accountHelper.onSwitch(redditClient -> {
            // By default, JRAW logs HTTP activity to System.out. We're going to use Log.i()
            // instead.
            LogAdapter logAdapter = new SimpleAndroidLogAdapter(Log.INFO);

            // We're going to use the LogAdapter to write down the summaries produced by
            // SimpleHttpLogger
            redditClient.setLogger(
                    new SimpleHttpLogger(SimpleHttpLogger.DEFAULT_LINE_LENGTH, logAdapter));

            // If you want to disable logging, use a NoopHttpLogger instead:
            // redditClient.setLogger(new NoopHttpLogger());

            return null;
        });
    }

    public static AccountHelper getAccountHelper() { return accountHelper; }
    public static SharedPreferencesTokenStore getTokenStore() { return tokenStore; }
}

Now you can start using JRAW! The example app fully implements the reddit authentication process. I highly encourage you to build and install the app and read the source code to get a better understanding of the whole process.

Javadoc

JRAW-Android uses JitPack to host its Javadoc.

https://jitpack.io/com/github/mattbdean/JRAW-Android/VERSION/javadoc/index.html

VERSION can be a specific commit hash (like 9390529), a tag, or the HEAD of a branch (like master-SNAPSHOT).

JitPack produces Javadoc only when necessary, so the first time someone accesses the Javadoc for a specific build it may take a little bit.

FAQ

How do I pass data around?

All JRAW models implement Serializable, so methods like Parcel.writeSerializable and Bundle.getSerializable should work fine. You can also transform models to/from JSON if you're concerned about speed:

// The serializeNulls() here is very important
JsonAdapter<Submission> adapter = JrawUtils.moshi.adapter(Submission.class).serializeNulls();
String json = adapter.toJson(someSubmission);

// Add the JSON to your Bundle/Parcel/whatever
bundle.putString("mySubmission", json);

// Later...
Submission pojo = adapter.fromJson(bundle.getString("mySubmission"));
someSubmission.equals(pojo); // => true

See mattbdean/JRAW#221 for why the adapter needs to serialize nulls.

How do I use a different version of JRAW (i.e. from JitPack)?

To use a different version of JRAW than the one directly depended on by JRAW-Android, use this:

repositories {
    // Assuming that you want to use a JitPack build
    maven { url 'https://jitpack.io' }
}
dependencies {
    compile('net.dean.jraw:JRAW-Android:1.0.0') {
        // Don't use the version of JRAW that JRAW-Android depends on
        exclude group: 'net.dean.jraw'
    }
    // JRAW-Android still expects JRAW classes to be available on the classpath. Include a specific
    // version of them via JitPack. See https://jitpack.io/#mattbdean/JRAW for more information.
    compile 'com.github.mattbdean:JRAW:<tag>'
}

Versioning

Unless otherwise noted, JRAW-Android's version is the same as JRAW. So JRAW-Android v1.1.0 would use JRAW v1.1.0.

Contributing

This project uses Robolectric for unit tests. Linux and Mac users on Android Studio should see this when running tests through the IDE.

worker8/JRAW-Android