Core Configuration and Authentication

interface Twitter {
    /**
     * Returns a new Twitter instance with builder pattern configuration
     */
    static TwitterBuilder newBuilder();
    
    /**
     * Returns a new Twitter instance with default configuration
     * Equivalent to newBuilder().build()
     */
    static Twitter getInstance();
    
    /**
     * Provides access to Twitter API v1.1 functionality
     */
    TwitterV1 v1();
}

class TwitterBuilder {
    /**
     * Configure OAuth 1.0a consumer credentials
     */
    TwitterBuilder oAuthConsumer(String consumerKey, String consumerSecret);
    
    /**
     * Configure OAuth 1.0a access token credentials
     */
    TwitterBuilder oAuthAccessToken(String accessToken, String accessTokenSecret);
    
    /**
     * Configure OAuth 2.0 bearer token for application-only authentication
     */
    TwitterBuilder oAuth2AccessToken(String oauth2AccessToken);
    
    /**
     * Add connection lifecycle listener for monitoring
     */
    TwitterBuilder connectionLifeCycleListener(ConnectionLifeCycleListener listener);
    
    /**
     * Add stream listener for real-time data processing
     */
    TwitterBuilder listener(StreamListener streamListener);
    
    /**
     * Add raw stream listener for JSON data processing
     */
    TwitterBuilder listener(RawStreamListener rawStreamListener);
    
    /**
     * Configure status event handler
     */
    TwitterBuilder onStatus(Consumer<Status> onStatus);
    
    /**
     * Configure exception handler
     */
    TwitterBuilder onException(Consumer<Exception> onException);
    
    /**
     * Build configured Twitter instance
     */
    Twitter build();
}

class OAuthAuthorization implements Authorization {
    /**
     * Create new OAuthAuthorization builder
     */
    static OAuthAuthorizationBuilder newBuilder();
    
    /**
     * Create OAuthAuthorization with consumer credentials
     */
    static OAuthAuthorization getInstance(String consumerKey, String consumerSecret);
    
    /**
     * Create OAuthAuthorization with default configuration
     */
    static OAuthAuthorization getInstance();
    
    /**
     * Get OAuth request token to start authorization flow
     */
    RequestToken getOAuthRequestToken() throws TwitterException;
    
    /**
     * Get OAuth request token with callback URL
     */
    RequestToken getOAuthRequestToken(String callbackURL) throws TwitterException;
    
    /**
     * Get OAuth access token (requires prior authorization)
     */
    AccessToken getOAuthAccessToken() throws TwitterException;
    
    /**
     * Get OAuth access token with verifier PIN/code
     */
    AccessToken getOAuthAccessToken(String oauthVerifier) throws TwitterException;
    
    /**
     * Get OAuth access token using request token
     */
    AccessToken getOAuthAccessToken(RequestToken requestToken) throws TwitterException;
    
    /**
     * Get OAuth access token using request token and verifier
     */
    AccessToken getOAuthAccessToken(RequestToken requestToken, String oauthVerifier) throws TwitterException;
    
    /**
     * Check if authorization is enabled
     */
    boolean isEnabled();
}

class AccessToken {
    /**
     * Create access token with credentials
     */
    AccessToken(String token, String tokenSecret);
    
    /**
     * Get access token string
     */
    String getToken();
    
    /**
     * Get access token secret
     */
    String getTokenSecret();
    
    /**
     * Get authorized user ID
     */
    long getUserId();
    
    /**
     * Get authorized user screen name
     */
    String getScreenName();
}

class RequestToken {
    /**
     * Get request token for authorization flow
     */
    String getToken();
    
    /**
     * Get request token secret
     */
    String getTokenSecret();
    
    /**
     * Get authorization URL for user consent
     */
    String getAuthorizationURL();
    
    /**
     * Get authentication URL for user login
     */
    String getAuthenticationURL();
}

// Basic OAuth 1.0a with existing tokens
Twitter twitter = Twitter.newBuilder()
    .oAuthConsumer("your_consumer_key", "your_consumer_secret")
    .oAuthAccessToken("user_access_token", "user_access_token_secret")
    .build();

// Access API with full user permissions
TwitterV1 v1 = twitter.v1();
Status status = v1.tweets().updateStatus("Hello Twitter!");

// Step 1: Get request token
OAuthAuthorization oauth = OAuthAuthorization.getInstance("consumer_key", "consumer_secret");
RequestToken requestToken = oauth.getOAuthRequestToken("http://your-app.com/callback");

// Step 2: Direct user to authorization URL
String authUrl = requestToken.getAuthorizationURL();
System.out.println("Open this URL and authorize the app: " + authUrl);

// Step 3: Get access token after user authorization
// For PIN-based flow (desktop apps):
Scanner scanner = new Scanner(System.in);
System.out.print("Enter the PIN: ");
String pin = scanner.nextLine();
AccessToken accessToken = oauth.getOAuthAccessToken(requestToken, pin);

// For callback-based flow (web apps):
// String oauthVerifier = extractFromCallback(); // Extract from callback URL
// AccessToken accessToken = oauth.getOAuthAccessToken(requestToken, oauthVerifier);

// Step 4: Create Twitter instance with access token
Twitter twitter = Twitter.newBuilder()
    .oAuthConsumer("consumer_key", "consumer_secret")
    .oAuthAccessToken(accessToken.getToken(), accessToken.getTokenSecret())
    .build();

class OAuth2Authorization implements Authorization {
    /**
     * Create new OAuth2Authorization builder
     */
    static OAuth2AuthorizationBuilder newBuilder();
    
    /**
     * Create OAuth2Authorization with consumer credentials
     */
    static OAuth2Authorization getInstance(String consumerKey, String consumerSecret);
    
    /**
     * Get OAuth 2.0 bearer token for application-only authentication
     */
    OAuth2Token getOAuth2Token() throws TwitterException;
    
    /**
     * Check if authorization is enabled
     */
    boolean isEnabled();
}

class OAuth2Token {
    /**
     * Create OAuth 2.0 token
     */
    OAuth2Token(String tokenType, String accessToken);
    
    /**
     * Get token type (typically "bearer")
     */
    String getTokenType();
    
    /**
     * Get access token string
     */
    String getAccessToken();
}

// Basic OAuth 2.0 with existing bearer token
Twitter twitter = Twitter.newBuilder()
    .oAuth2AccessToken("your_bearer_token")
    .build();

// Read-only access (no posting capabilities)
TwitterV1 v1 = twitter.v1();
QueryResult results = v1.search().search(new Query("Twitter4J"));

// Step 1: Get OAuth 2.0 bearer token
OAuth2Authorization oauth2 = OAuth2Authorization.getInstance("consumer_key", "consumer_secret");
OAuth2Token bearerToken = oauth2.getOAuth2Token();

// Step 2: Create Twitter instance with bearer token
Twitter twitter = Twitter.newBuilder()
    .oAuth2AccessToken(bearerToken.getAccessToken())
    .build();

// Step 3: Use for read-only operations
TwitterV1 v1 = twitter.v1();
QueryResult searchResults = v1.search().search(new Query("machine learning"));
ResponseList<Status> timeline = v1.timelines().getUserTimeline("twitter");

oauth.consumerKey=your_consumer_key
oauth.consumerSecret=your_consumer_secret
oauth.accessToken=your_access_token  
oauth.accessTokenSecret=your_access_token_secret

# Or OAuth 2.0
oauth2.tokenType=bearer
oauth2.accessToken=your_bearer_token

# HTTP settings
http.connectionTimeout=20000
http.readTimeout=120000
http.retryCount=3

# API URLs (usually defaults are fine)
restBaseURL=https://api.twitter.com/1.1/
streamBaseURL=https://stream.twitter.com/1.1/
uploadBaseURL=https://upload.twitter.com/1.1/

interface Configuration {
    /**
     * Get OAuth consumer key
     */
    String getOAuthConsumerKey();
    
    /**
     * Get OAuth consumer secret  
     */
    String getOAuthConsumerSecret();
    
    /**
     * Get OAuth access token
     */
    String getOAuthAccessToken();
    
    /**
     * Get OAuth access token secret
     */
    String getOAuthAccessTokenSecret();
    
    /**
     * Get OAuth 2.0 access token
     */
    String getOAuth2AccessToken();
    
    /**
     * Get REST API base URL
     */
    String getRestBaseURL();
    
    /**
     * Get Streaming API base URL  
     */
    String getStreamBaseURL();
    
    /**
     * Get HTTP connection timeout in milliseconds
     */
    int getHttpConnectionTimeout();
    
    /**
     * Get HTTP read timeout in milliseconds
     */
    int getHttpReadTimeout();
}

class TwitterException extends Exception {
    /**
     * Get Twitter-specific error code
     */
    int getErrorCode();
    
    /**
     * Get error message from Twitter API
     */
    String getErrorMessage();
    
    /**
     * Get HTTP status code
     */
    int getStatusCode();
    
    /**
     * Check if error was caused by network issues
     */
    boolean isCausedByNetworkIssue();
    
    /**
     * Check if error message is available
     */
    boolean isErrorMessageAvailable();
    
    /**
     * Check if error is due to rate limiting
     */
    boolean exceededRateLimitation();
    
    /**
     * Get rate limit status if available
     */
    RateLimitStatus getRateLimitStatus();
    
    /**
     * Check if retry after period is specified
     */
    boolean isRetryAfter();
    
    /**
     * Get retry after period in seconds
     */
    int getRetryAfter();
}

interface RateLimitStatus {
    /**
     * Get rate limit for this endpoint
     */
    int getLimit();
    
    /**
     * Get remaining calls in current window
     */
    int getRemaining();
    
    /**
     * Get reset time as Unix timestamp
     */
    int getResetTimeInSeconds();
    
    /**
     * Get seconds until rate limit resets
     */
    int getSecondsUntilReset();
}

interface TwitterResponse {
    /**
     * Get rate limit status for this response
     */
    RateLimitStatus getRateLimitStatus();
    
    /**
     * Get access level for this response
     */
    int getAccessLevel();
}

try {
    ResponseList<Status> timeline = v1.timelines().getHomeTimeline();
    
    // Check rate limit status
    RateLimitStatus rateLimit = timeline.getRateLimitStatus();
    System.out.println("Remaining calls: " + rateLimit.getRemaining());
    System.out.println("Reset time: " + rateLimit.getResetTimeInSeconds());
    
} catch (TwitterException e) {
    if (e.exceededRateLimitation()) {
        System.out.println("Rate limit exceeded. Retry after: " + e.getRetryAfter());
    } else {
        System.out.println("API Error: " + e.getErrorMessage());
    }
}

// Step 1: Get request token
Twitter twitter = Twitter.newBuilder()
    .oAuthConsumer("consumer_key", "consumer_secret")
    .build();

RequestToken requestToken = twitter.getOAuthRequestToken();

// Step 2: Redirect user to authorization URL
String authUrl = requestToken.getAuthorizationURL();
System.out.println("Visit: " + authUrl);

// Step 3: Get access token with PIN/verifier
Scanner scanner = new Scanner(System.in);
System.out.print("Enter PIN: ");
String pin = scanner.nextLine();

AccessToken accessToken = twitter.getOAuthAccessToken(requestToken, pin);

// Step 4: Configure Twitter instance with access token
Twitter authorizedTwitter = Twitter.newBuilder()
    .oAuthConsumer("consumer_key", "consumer_secret") 
    .oAuthAccessToken(accessToken.getToken(), accessToken.getTokenSecret())
    .build();

// Application-only authentication for read-only access
Twitter twitter = Twitter.newBuilder()
    .oAuthConsumer("consumer_key", "consumer_secret")
    .build();

// Get bearer token
OAuth2Token oauth2Token = twitter.getOAuth2Token();

// Configure with bearer token
Twitter appOnlyTwitter = Twitter.newBuilder()
    .oAuth2AccessToken(oauth2Token.getAccessToken())
    .build();