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