Package com.mooltiverse.oss.nyx.services.github

Class GitHub

java.lang.Object

com.mooltiverse.oss.nyx.services.github.GitHub

All Implemented Interfaces:

GitService

public class GitHub
extends Object
implements GitService

The entry point to the GitHub service.

Field Summary

Fields

Modifier and Type	Field	Description
static String	API_BASE_URL	The API base URL, as per GitHub API

Method Summary

Modifier and Type	Method	Description
GitHubSession	authenticateWithToken(String token)	Authenticates by using the given token (Personal Access Token, OAuth)
URI	getBaseURI()	Returns the API base URI for the service instance.
static GitHub	instance()	Returns an instance using the default API URI (API_BASE_URL).
static GitHub	instance(String apiURI)	Returns an instance using the given API URI.
static GitHub	instance(URI apiURI)	Returns an instance using the given API URI.
boolean	ping()	Tries to contact the remote server to verify it's reachable and healthy.
boolean	supports(GitServiceFeature feature)	Safely checks if the underlying implementation supports the given operation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

API_BASE_URL

public static final String API_BASE_URL

The API base URL, as per GitHub API

See Also:

Constant Field Values

Method Detail

instance

public static GitHub instance()
                       throws GitTransportException

Returns an instance using the default API URI (API_BASE_URL).

Returns:

an instance using the default API URI.

Throws:

GitTransportException - if the default URI can't be reached or does not expose valid APIs

instance

public static GitHub instance(String apiURI)
                       throws GitTransportException

Returns an instance using the given API URI.

Parameters:

apiURI - the API URI, which is usually the endpoint to a private or on premises installation

Returns:

an instance using the given API URI

Throws:

GitTransportException - if the given URI can't be reached or does not expose valid APIs

NullPointerException - if the given URI is null

IllegalArgumentException - if the given URI is illegal (i.e. empty or malformed)

instance

public static GitHub instance(URI apiURI)
                       throws GitTransportException

Returns an instance using the given API URI.

Parameters:

apiURI - the API URI, which is usually the endpoint to a private or on premises installation

Returns:

an instance using the given API URI

Throws:

GitTransportException - if the given URI can't be reached or does not expose valid APIs

NullPointerException - if the given URI is null

IllegalArgumentException - if the given URI is illegal (i.e. empty or malformed)

supports

public boolean supports(GitServiceFeature feature)

Safely checks if the underlying implementation supports the given operation. If this method returns true then the underlying class will not raise any UnsupportedOperationException when invoking the specific methods.

Specified by:

supports in interface GitService

Parameters:

feature - the feature to check for support.

Returns:

true if the operation is supported, false otherwise

getBaseURI

public URI getBaseURI()

Returns the API base URI for the service instance.

Specified by:

getBaseURI in interface GitService

Returns:

the API base URI for the service instance

ping

public boolean ping()

Tries to contact the remote server to verify it's reachable and healthy. Please note that this method sends unauthenticated requests that may fail because of rate limits so use it with care.

Specified by:

ping in interface GitService

Returns:

true if the operation succeeds, false otherwise

authenticateWithToken

public GitHubSession authenticateWithToken(String token)
                                    throws GitTransportException,
                                           GitAuthenticationException

Authenticates by using the given token (Personal Access Token, OAuth)

Specified by:

authenticateWithToken in interface GitService

Parameters:

token - the token to use for authentication.

Returns:

a session object that can be used to perform operations as an authenticated user

Throws:

GitTransportException - if a transport related error occurs while communicating with the server

GitAuthenticationException - if authentication fails