repository·master·Indexed 18 days ago
https://github.com/mattbdean/jrawA Java Reddit API Wrapper for the JVM that provides a structured way to interact with Reddit's API. It supports OAuth2 authentication, various network adapters, and includes a dedicated extension library for Android integration.
JRAW is organized into several functional packages that handle different aspects of interacting with the Reddit API:
net.dean.jraw: The core central classes of the library.net.dean.jraw.databind: Handles JSON to POJO (Plain Old Java Object) conversions using the Moshi library.net.dean.jraw.http: Manages HTTP request/response lifecycle and logging, built on top of OkHttp.net.dean.jraw.models: Contains data classes representing the structure of Reddit API responses.net.dean.jraw.oauth: Manages Reddit's primary authentication method.net.dean.jraw.pagination: Provides helpers for navigating paginated endpoints (e.g., subreddits or front page).net.dean.jraw.ratelimit: Provides mechanisms to restrict request frequency to comply with API limits.net.dean.jraw.references: Contains the basic building blocks of the JRAW API.net.dean.jraw.tree: Specialized classes for handling comment trees.net.dean.jraw.websocket: Provides helpers for WebSocket communication.Reference objects. A Reference is a lightweight, immutable, and abstract pointer to a Reddit resource (like a user, subreddit, or comment). A Reference does not guarantee that the resource exists; it simply represents the location of that resource. You create Reference objects starting from a RedditClient or by deriving them from other existing Reference objects.JRAW uses OkHttp for HTTP requests and WebSocket connections, and Moshi for JSON (de)serialization.
When consuming Reddit API data, you have three primary ways to handle the JSON structure:
Map<String, Object>. This is easy but requires manual type casting and knowledge of exact JSON keys.@Json annotations. This provides type safety but requires significant boilerplate (getters, equals, hashCode, toString).The RedditClient class is the central entry point for JRAW. It is responsible for:
RedditClient is the only class capable of sending requests to the Reddit API (with the exception of certain OAuth2 operations). All other classes that require network access or WebSocket connections do so through a RedditClient instance.
By default, the RedditClient manages Reddit's OAuth2 API limit (60 requests per minute) using a conservative strategy. It allows one request per second with a 'burst' capacity of up to five requests at a time.
Burst Behavior Example: If there has been no activity for at least five seconds and you suddenly trigger ten requests:
This default behavior is designed to prevent hitting Reddit's denial threshold without requiring manual configuration.
Instead of polling for updates using latestUpdates at a fixed interval, you can leverage WebSockets to receive real-time notifications when something happens to a live thread. This is more efficient for reacting to new content as it arrives.
// Example of leveraging WebSockets for real-time updates
LiveThreads.websocket(thread, (event) -> {
// Handle real-time event
});The JRAW documentation is a meta-project that generates Markdown files for hosting on GitBook. It uses a system of @CodeSample annotations and special syntax to ensure code samples in the documentation are always syntactically valid and up-to-date with the source code.
Code samples are defined in the net.dean.jraw.docs.samples package. Any method annotated with @CodeSample can be referenced in Markdown files.
To include a code sample in a Markdown file (located in src/main/resources/content), use the following syntax:
{{ @ClassName.methodName }}
Note: A code sample must be the only thing on its line.
You can link directly to Javadoc for JRAW classes using the [[@ClassName]] syntax. This automatically generates a link to the corresponding HTML documentation.
Note: For Enums, you must use the fully qualified class name (e.g., [[@com.example.MyEnum]]).
// In net.dean.jraw.docs.samples
final class Example {
@CodeSample
void showSomething() {
String x = "foo";
System.out.println(x);
}
}{{ @Example.showSomething }}
Lorem ipsum [[@RedditClient]] sit amet.Reddit provides three types of OAuth2 apps. Choosing the correct one depends on where your code runs and whether it can keep a secret:
Additionally, Installed and Web apps can operate in "userless" (application-only) mode, which allows access to the API without requiring a specific user to authorize it.
Access tokens expire after one hour. JRAW can refresh them automatically depending on your authentication method:
requestRefreshToken to true when generating the authorization URL.// Ensure refresh token is requested during interactive auth
String url = authHelper.getAuthorizationUrl(true); // true = requestRefreshTokenReddit API pagination is managed through the Listing structure. A Listing contains the data for a single page and the ID of the next model in the sequence.
JRAW abstracts this complexity using Paginator objects. A Paginator tracks the last Listing received and manages the logic for requesting subsequent pages. There are two main types of paginators:
top), and an optional time period (e.g., hour).Note that not all endpoints support sorting or time periods, so you must choose the paginator type compatible with your target endpoint.
Most Reddit API responses are wrapped in an "envelope" structure, which typically looks like this:
{
"kind": "t2",
"data": { ... }
}In this structure, kind indicates the type of object (e.g., t2 for an account), and the actual object resides inside the data node.
To allow JRAW to automatically unwrap these envelopes during deserialization, annotate your @AutoValue model classes with @RedditModel. This enables the use of the RedditModelAdapterFactory to map the contents of the data node directly to your class.
@AutoValue
@RedditModel
abstract class Account {
// ...
}