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

Class GitHub

java.lang.Object
com.mooltiverse.oss.nyx.services.github.GitHub
All Implemented Interfaces:
GitHostingService, ReleaseService, Service, UserService
public class GitHub extends Object implements GitHostingService, ReleaseService, UserService
The entry point to the GitHub remote service.

  • Field Details

    • BASE_URI_OPTION_NAME

      public static final String BASE_URI_OPTION_NAME
      The name of the option used to pass the base URI to this object instance. This is the value of the key inside the options passed to get a new instance of this class. If this option is not passed the default URI is used. Value: "BASE_URI"
      See Also:

    • AUTHENTICATION_TOKEN_OPTION_NAME

      public static final String AUTHENTICATION_TOKEN_OPTION_NAME
      The name of the option used to pass the authentication token (Personal Access Token, OAuth) to this object instance. This is the value of the key inside the options passed to get a new instance of this class. If this option is not passed the service will not be able to authenticate and perform any of the authentication protected operations. Value: "AUTHENTICATION_TOKEN"
      See Also:

    • REMOTES_OPTION_NAME

      public static final String REMOTES_OPTION_NAME
      The name of the option used to pass the list of supported remotes to this object instance. This is the value of the key inside the options passed to get a new instance of this class. If this option is not passed the service will not be able to perform some of its operations. Value: "REMOTES"
      See Also:

    • REPOSITORY_NAME_OPTION_NAME

      public static final String REPOSITORY_NAME_OPTION_NAME
      The name of the option used to pass the name of the Git repository to this object instance. If the repository is https://github.com/octocat/hello-world, the value to pass for this option is hello-world. This is the value of the key inside the options passed to get a new instance of this class. If this option is not passed the service will not be able to perform some of its operations. Value: "REPOSITORY_NAME"
      See Also:

    • REPOSITORY_OWNER_OPTION_NAME

      public static final String REPOSITORY_OWNER_OPTION_NAME
      The name of the option used to pass the owner of the Git repository to this object instance. If the repository is https://github.com/octocat/hello-world, the value to pass for this option is octocat. This option accepts individual and organization names. This is the value of the key inside the options passed to get a new instance of this class. If this option is not passed the service will not be able to perform some of its operations. Value: "REPOSITORY_OWNER"
      See Also:

  • Method Details

    • instance

      public static GitHub instance(Map<String,String> options)
      Returns an instance using the given options.
      Parameters:
      options - the map of options for the requested service. It can't be null. Valid options are documented as constants on this class.
      Returns:
      an instance using the given options.
      Throws:
      NullPointerException - if the given options map is null
      IllegalArgumentException - if some entries in the given options map are missing or illegal for some reason

    • createGitRepository

      public GitHubRepository createGitRepository(String name, String description, boolean restricted, boolean initialize) throws SecurityException, TransportException
      Creates a new Git repository for the currently authenticated user.
      Please note that if the service has been configured with repository owner and name those attributes are ignored by this method as the owner is always the authenticated user (the one owning the configured credentials) and the name is always the name attribute.
      Specified by:
      createGitRepository in interface GitHostingService
      Parameters:
      name - the repository name. Cannot be null
      description - the repository description. It may be null
      restricted - when true the repository will have private visibility, otherwise it will be public
      initialize - when true the repository is also initialized (usually with a default README file)
      Returns:
      the object representing the newly created repository
      Throws:
      SecurityException - if authentication or authorization fails or there is no currently authenticated user
      TransportException - if communication to the remote endpoint fails

    • deleteGitRepository

      public void deleteGitRepository(String name) throws SecurityException, TransportException
      Deletes a Git repository for the currently authenticated user.
      Please note that if the service has been configured with repository owner and name those attributes are ignored by this method as the owner is always the authenticated user (the one owning the configured credentials) and the name is always the name attribute.
      Specified by:
      deleteGitRepository in interface GitHostingService
      Parameters:
      name - the repository name. Cannot be null
      Throws:
      SecurityException - if authentication or authorization fails or there is no currently authenticated user
      TransportException - if communication to the remote endpoint fails

    • getAuthenticatedUser

      public GitHubUser getAuthenticatedUser() throws TransportException, SecurityException
      Retrieves informations about the currently authenticated user. The authenticated user is the one owning the configured credentials.
      Specified by:
      getAuthenticatedUser in interface UserService
      Returns:
      the authenticated user
      Throws:
      TransportException - if communication to the remote endpoint fails
      SecurityException - if authentication or authorization fails or there is no currently authenticated user

    • getReleaseByTag

      public GitHubRelease getReleaseByTag(String owner, String repository, String tag) throws SecurityException, TransportException
      Finds the release in the given repository by the release tag.
      Specified by:
      getReleaseByTag in interface ReleaseService
      Parameters:
      owner - the name of the repository owner to get the release for. It may be null, in which case, the repository owner must be passed as a service option (see services implementing this interface for more details on the options they accept). If not null this value overrides the option passed to the service.
      repository - the name of the repository to get the release for. It may be null, in which case, the repository name must be passed as a service option (see services implementing this interface for more details on the options they accept). If not null this value overrides the option passed to the service.
      tag - the tag the release refers to (i.e. 1.2.3, v4.5.6). It can't be null
      Returns:
      the release for the given tag, or null if there is no such release
      Throws:
      SecurityException - if authentication or authorization fails
      TransportException - if communication to the remote endpoint fails

    • publishRelease

      public GitHubRelease publishRelease(String owner, String repository, String title, String tag, String description, Map<String,Object> options) throws SecurityException, TransportException
      Publishes a new release.
      Specified by:
      publishRelease in interface ReleaseService
      Parameters:
      owner - the name of the repository owner to create the release for. It may be null, in which case, the repository owner must be passed as a service option (see services implementing this interface for more details on the options they accept). If not null this value overrides the option passed to the service.
      repository - the name of the repository to create the release for. It may be null, in which case, the repository name must be passed as a service option (see services implementing this interface for more details on the options they accept). If not null this value overrides the option passed to the service.
      title - the release title, it may be the same of tag but not necessarily. It may be null
      tag - tag to publish the release for (i.e. 1.2.3, v4.5.6). It can't be null
      description - the release description. This is usually a Markdown text containing release notes or a changelog or something like that giving an overall description of the release
      options - the optional map of release options (ReleaseService.RELEASE_OPTION_DRAFT, ReleaseService.RELEASE_OPTION_PRE_RELEASE). When null no options are evaluated.
      Returns:
      the newly created release
      Throws:
      SecurityException - if authentication or authorization fails
      TransportException - if communication to the remote endpoint fails

    • publishReleaseAssets

      public GitHubRelease publishReleaseAssets(String owner, String repository, Release release, Set<Attachment> assets) throws SecurityException, TransportException
      Publishes a set of assets for a release. Even when the service supports the Service.Feature.RELEASE_ASSETS feature not all types of assets may be supported. Please check the implementation class for any restrictions on the supported assets.
      Specified by:
      publishReleaseAssets in interface ReleaseService
      Parameters:
      owner - the name of the repository owner to create the assets for. It may be null, in which case, the repository owner must be passed as a service option (see services implementing this interface for more details on the options they accept). If not null this value overrides the option passed to the service.
      repository - the name of the repository to create the assets for. It may be null, in which case, the repository name must be passed as a service option (see services implementing this interface for more details on the options they accept). If not null this value overrides the option passed to the service.
      release - the release to publish the assets for. It must be an object created by the same service implementation
      assets - the set of assets to publish. Assets may be interpreted differently depending on their path and type. Please check the implementation class for restrictions on the supported assets
      Returns:
      the given release with also the links to the uploaded assets. The returned object represents the same release provided as parameter but may be a different instance. Only the assets that were actually published are returned while those not supported by the implementing service are not within the list of assets referred by the returned object
      Throws:
      SecurityException - if authentication or authorization fails
      TransportException - if communication to the remote endpoint fails

    • supports

      public boolean supports(Service.Feature 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 Service
      Parameters:
      feature - the feature to check for support.
      Returns:
      true if the operation is supported, false otherwise