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.1.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.