Package com.ellucian.ethos.integration.client.config

Class EthosConfigurationClient

  • public class EthosConfigurationClient
extends EthosClient
    An EthosClient used to retrieve configuration data from Ethos Integration. This could include things like available versions of a given Ethos resource, and other data available from the /appConfig and/or admin/available-resources Ethos Integration APIs.

    Note that the preferred way to instantiate this class is through the EthosClientBuilder.

    • Field Detail

      • JSON_ACCESSOR_RESOURCES

        public static final String JSON_ACCESSOR_RESOURCES
        Constant used when accessing a resources property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_NAME

        public static final String JSON_ACCESSOR_NAME
        Constant used when accessing a name property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_ID

        public static final String JSON_ACCESSOR_ID
        Constant used when accessing an id property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_APPID

        public static final String JSON_ACCESSOR_APPID
        Constant used when accessing an appId property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_APPICATIONID

        public static final String JSON_ACCESSOR_APPICATIONID
        Constant used when accessing an applicationId property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_APPNAME

        public static final String JSON_ACCESSOR_APPNAME
        Constant used when accessing an appName property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_RESOURCE

        public static final String JSON_ACCESSOR_RESOURCE
        Constant used when accessing a resource property path from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_RESOURCE_NAME

        public static final String JSON_ACCESSOR_RESOURCE_NAME
        Constant used when accessing a resource/name property path from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_RESOURCENAME

        public static final String JSON_ACCESSOR_RESOURCENAME
        Constant used when accessing a resourceName property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_RESOURCE_REPRESENTATIONS

        public static final String JSON_ACCESSOR_RESOURCE_REPRESENTATIONS
        Constant used when accessing a resource/representations property path from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_REPRESENTATIONS

        public static final String JSON_ACCESSOR_REPRESENTATIONS
        Constant used when accessing a representations property path from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_XMEDIATYPE

        public static final String JSON_ACCESSOR_XMEDIATYPE
        Constant used when accessing an X-Media-Type property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_VERSIONS

        public static final String JSON_ACCESSOR_VERSIONS
        Constant used when accessing a versions property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_VERSION

        public static final String JSON_ACCESSOR_VERSION
        Constant used when accessing a version property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_OWNEROVERRIDES

        public static final String JSON_ACCESSOR_OWNEROVERRIDES
        Constant used when accessing an ownerOverrides property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_NAMEDQUERIES

        public static final String JSON_ACCESSOR_NAMEDQUERIES
        Constant used when accessing a namedQueries property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_ACCESSOR_FILTERS

        public static final String JSON_ACCESSOR_FILTERS
        Constant used when accessing a filters property from a JsonNode.
        See Also:
        Constant Field Values

      • JSON_SETTER_RESOURCE

        public static final String JSON_SETTER_RESOURCE
        Constant used when setting a resource property on a JsonNode.
        See Also:
        Constant Field Values

      • JSON_SETTER_APPID

        public static final String JSON_SETTER_APPID
        Constant used when setting an appId property on a JsonNode.
        See Also:
        Constant Field Values

      • JSON_SETTER_APPNAME

        public static final String JSON_SETTER_APPNAME
        Constant used when setting an appName property on a JsonNode.
        See Also:
        Constant Field Values

      • JSON_SETTER_VERSION

        public static final String JSON_SETTER_VERSION
        Constant used when setting a version property on a JsonNode.
        See Also:
        Constant Field Values

      • JSON_SETTER_VERSIONS

        public static final String JSON_SETTER_VERSIONS
        Constant used when setting a versions property on a JsonNode.
        See Also:
        Constant Field Values

      • JSON_SETTER_RESOURCENAME

        public static final String JSON_SETTER_RESOURCENAME
        Constant used when setting a resourceName property on a JsonNode.
        See Also:
        Constant Field Values

      • JSON_SETTER_NAMEDQUERIES

        public static final String JSON_SETTER_NAMEDQUERIES
        Constant used when setting a namedQuery property on a JsonNode.
        See Also:
        Constant Field Values

      • JSON_SETTER_FILTERS

        public static final String JSON_SETTER_FILTERS
        Constant used when setting a filters property on a JsonNode.
        See Also:
        Constant Field Values

      • FULL_VERSION_TAG

        public static String FULL_VERSION_TAG
        The tag used as a placeholder for the version value in the FULL_VERSION string.

      • FULL_VERSION

        public static String FULL_VERSION
        Pattern used to provide the full version of a given resource.

    • Constructor Detail

      • EthosConfigurationClient

        public EthosConfigurationClient​(String apiKey,
                                Integer connectionTimeout,
                                Integer connectionRequestTimeout,
                                Integer socketTimeout)
        Public constructor taking a sessionToken parameter.

        Note that the preferred way to instantiate this class is through the EthosClientBuilder.

        Parameters:
        apiKey - A valid API key from Ethos Integration. This is required to be a valid 36 character GUID string. If it is null, empty, or not in a valid GUID format, then an IllegalArgumentException will be thrown.
        connectionTimeout - The timeout in seconds for a connection to be established.
        connectionRequestTimeout - The timeout in seconds when requesting a connection from the Apache connection manager.
        socketTimeout - The timeout in seconds when waiting for data between consecutive data packets.

    • Method Detail

      • getAppConfig

        public String getAppConfig()
                    throws IOException
        Get application configuration info from Ethos Integration. This returns the configuration data for the application that this client's session token belongs to.
        Returns:
        The config info for your app in string format.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getAppConfigJson

        public com.fasterxml.jackson.databind.JsonNode getAppConfigJson()
                                                         throws IOException
        Get application configuration as a JsonNode object from Ethos Integration. This returns the configuration data for the application that this client's session token belongs to.

        The following is an example of the JSON data structure contained within the returned ArrayNode: 

         {
     "id": "11111111-1111-1111-1111-111111111111",
     "name": "client app",
     "subscriptions": [
         {
             "resourceName": "academic-levels",
             "applicationId": "22222222-2222-2222-2222-222222222222"
         }
     ],
     "ownerOverrides": [
         {
             "resourceName": "academic-credentials",
             "applicationId": "22222222-2222-2222-2222-222222222222"
         },
         {
             "resourceName": "academic-disciplines",
             "applicationId": "22222222-2222-2222-2222-222222222222"
         },
        ],
        "metadata": {
         "createdBy": "someone@ellucian.me",
         "createdOn": "2020-07-21T17:58:59.880Z",
         "modifiedBy": "someone@ellucian.me",
         "modifiedOn": "2020-10-27T16:28:34.979Z",
         "version": "4.9.2"
     }
 }
        Returns:
        The config info for your app as a JsonNode object.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getAllAvailableResources

        public String getAllAvailableResources()
                                throws IOException
        Get the details about all the available resources in the tenant associated with this client's session token.
        Returns:
        The available resources details in string format.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getAllAvailableResourcesAsJson

        public com.fasterxml.jackson.databind.JsonNode getAllAvailableResourcesAsJson()
                                                                       throws IOException
        Get the details about all the available resources in the tenant associate with this client's session token as a List of JsonNodes.

        The following is an example of the JSON data structure contained within the returned ArrayNode: 

         [
   {
      "id": "11111111-1111-1111-11111111111111111",
      "name": "Banner Student API",
      "about": [
          {
              "applicationName": "StudentApi",
              "applicationVersion": "9.21",
              "name": "StudentApi",
              "version": "9.21"
          }
      ],
      "resources": [
          {
              "name": "academic-credentials",
              "representations": [
                  {
                      "filters": [ "type" ],
                      "X-Media-Type": "application/vnd.hedtech.integration.v6+json",
                      "methods": [ "get", "post", "put" ],
                      "version": "v6"
                  },
                  {
                      "filters": [ "type" ],
                      "X-Media-Type": "application/json",
                      "methods": [ "get", "post", "put" ]
                  }
              ]
          },
          {
              "name": "academic-disciplines",
              "representations": [
                  {
                      "filters": [ "type" ],
                      "X-Media-Type": "application/vnd.hedtech.integration.v7+json",
                      "methods": [ "get", "post", "put" ],
                      "version": "v7"
                  },
                  {
                      "filters": [ "type" ],
                      "X-Media-Type": "application/vnd.hedtech.integration.v10+json",
                      "methods": [ "get", "post", "put" ],
                      "version": "v10"
                  },
                  {
                      "filters": [ "type" ],
                      "X-Media-Type": "application/vnd.hedtech.integration.v15+json",
                      "methods": [ "get", "post", "put" ],
                      "namedQueries": [
                            {
                                "filters": [ "majorStatus" ],
                                "name": "majorStatus"
                            }
                      ],
                      "version": "v15"
                  },
                  {
                      "filters": [ "type" ],
                      "X-Media-Type": "application/json",
                      "methods": [ "get", "post", "put" ],
                      "namedQueries": [
                            {
                                "filters": [ "majorStatus" ],
                                "name": "majorStatus"
                            }
                      ]
                  }
              ]
          }
      ]
   }
 ]
        Returns:
        The available resources details as a JsonNode, or null if the response from available resources is null or empty.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getAvailableResourcesForAppAsJson

        public com.fasterxml.jackson.databind.node.ArrayNode getAvailableResourcesForAppAsJson()
                                                                                throws IOException
        Gets the details about the available resources an application points to, from the tenant associated with this client's session token. The results will be filtered based on the 'ownerOverrides' array from the session token application's configuration data.

        The following is an example of the JSON data structure contained within the returned ArrayNode: 

         [
    {
        "name": "academic-credentials",
              "representations": [
            {
               "filters": [ "type" ],
               "X-Media-Type": "application/vnd.hedtech.integration.v6+json",
               "methods": [ "get", "post", "put" ],
               "version": "v6"
            },
            {
                "filters": [ "type" ],
                "X-Media-Type": "application/json",
                "methods": [ "get", "post", "put" ]
            }
        ]
    },
    {
        "name": "academic-disciplines",
        "representations": [
            {
                "filters": [ "type" ],
                "X-Media-Type": "application/vnd.hedtech.integration.v7+json",
                "methods": [ "get", "post", "put" ],
                "version": "v7"
            },
            {
                "filters": [ "type" ],
                "X-Media-Type": "application/vnd.hedtech.integration.v10+json",
                "methods": [ "get", "post", "put" ],
                "version": "v10"
            },
            {
                "filters": [ "type" ],
                "X-Media-Type": "application/vnd.hedtech.integration.v15+json",
                "methods": [ "get", "post", "put" ],
                "namedQueries": [
                    {
                        "filters": [ "majorStatus" ],
                        "name": "majorStatus"
                    }
                ],
                "version": "v15"
            },
            {
                "filters": [ "type" ],
                "X-Media-Type": "application/json",
                "methods": [ "get", "post", "put" ],
                "namedQueries": [
                    {
                        "filters": [ "majorStatus" ],
                        "name": "majorStatus"
                    }
                ]
            }
        ]
    }
 ]
        Returns:
        An ArrayNode containing resource details, or an empty ArrayNode if the response from appConfig does not contain ownerOverrides or if the response from available resources is null or empty.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getAvailableResourcesForApp

        public String getAvailableResourcesForApp()
                                   throws IOException
        Get the details about the available resources an application points to, from the tenant associated with this client's session token. The results will be filtered based on the 'ownerOverrides' array from the session token application's configuration data.
        Returns:
        The available resources details in string format.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionHeadersForApp

        public List<String> getVersionHeadersForApp​(String resourceName)
                                     throws IOException
        Returns a list of version headers for the given resourceName filtered by the ownerOverrides property from appConfig. Returns a simple list of version headers because each resource is only listed once under ownerOverrides. The results will be filtered based on the resources available in the 'ownerOverrides' array from the session token application's configuration data. If resourceName not found in ownerOverrides, returns an empty List.
        Parameters:
        resourceName - The resource name for which to get a list of supported version headers.
        Returns:
        A list of version headers according to whether the given resource is found in the ownerOverrides property of appConfig, or an empty list if not found.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionsForApp

        public List<String> getVersionsForApp​(String resourceName)
                               throws IOException
        Returns a list of versions for the given resourceName filtered by the ownerOverrides property from appConfig. Returns a simple list of versions because each resource is only listed once under ownerOverrides. The results will be filtered based on the resources available in the 'ownerOverrides' array from the session token application's configuration data. If resourceName not found in ownerOverrides, returns an empty List.
        Parameters:
        resourceName - The resource name for which to get a list of supported versions.
        Returns:
        A list of versions according to whether the given resource is found in the ownerOverrides property of appConfig, or an empty list if not found. Each version in the list will be prefixed with the 'v' char, e.g. "v4.5".
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionListForOwnerOverrides

        protected List<String> getVersionListForOwnerOverrides​(com.fasterxml.jackson.databind.node.ArrayNode resourcesArrayNode,
                                                       String representationType)
        Intended to be used internally by the SDK.

        Extracts a list of versions as either a list of version headers or a list of version values depending on the representationType.

        Parameters:
        resourcesArrayNode - The ArrayNode containing a list of resources per the ownerOverrides configuration from appConfig.
        representationType - The type of version representation to extract, either "/version" for the version value, or "/X-Media-Type" for the version header value.
        Returns:
        A list of either version values or version headers per the representationType.

      • getResourceDetails

        public String getResourceDetails​(String resourceName)
                          throws IOException
        Get the details of a single resource from the tenant associated with this client's session token. The results will include details from each application in the tenant that owns the resource.

        The returned value will be in String format of a JSON array with each object containing the following properties:

        • appId - the ID of an owning application
        • appName - the name of an owning application
        • resource - the details of the resource

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty.

        Parameters:
        resourceName - The name of the resource for which to return details.
        Returns:
        The resource details in string format.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getResourceDetailsAsJson

        public com.fasterxml.jackson.databind.node.ArrayNode getResourceDetailsAsJson​(String resourceName)
                                                                       throws IOException
        Get the details of a single resource from the tenant associated with this client's session token. The results will include details from each application in the tenant that owns the resource.

        The format of the response will be a list of JsonNodes with each object containing the following properties:

        • appId - the ID of an owning application
        • appName - the name of an owning application
        • resource - the details of the resource

        The following is an example of the JSON data structure contained within the returned ArrayNode: 

         [
    {
        "appId": "11111111-1111-1111-1111-111111111111",
        "appName": "Banner Integration API",
        "resource": {
            "name": "persons",
            "representations": [
                {
                    "filters": [ "title", "firstName", "lastName", "role" ],
                    "X-Media-Type": "application/vnd.hedtech.integration.v6json",
                    "methods": [ "get", "post", "put" ],
                    "version": "v6"
                },
                {
                    "filters": [ "names.title", "names.firstName", "names.lastName", "roles.role" ],
                    "X-Media-Type": "application/vnd.hedtech.integration.v8json",
                    "methods": [ "get", "post", "put" ],
                    "namedQueries": [
                        {
                            "filters": [ "personFilter" ],
                            "name": "personFilter"
                        }
                    ],
                    "version": "v8"
                }
            ]
        }
    }
 ]

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty.
        Throws an EthosResourceNotFoundException (Runtime) if the given resourceName is not found in the available-resources response.

        Parameters:
        resourceName - The name of the resource for which to return details.
        Returns:
        An ArrayNode containing resource details, or an empty ArrayNode if resourceName is null or empty/blank.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getMajorVersionsOfResource

        public List<String> getMajorVersionsOfResource​(String resourceName)
                                        throws IOException
        Gets only the major version headers as a List of Strings for the given resource name. Gets the entire version header string of the resource also found in the Accept Header of the request containing only the major versioning notation: e.g. application/vnd.hedtech.integration.v12+json

        The following table shows examples given various supported versions.

        Supported resource versions and versions returned by the SDK:
        Resource Supports VersionsSDK Returns Version
        v12.2.1,
        v12,
        v12.0.0,
        v13.1.0
        application/vnd.hedtech.integration.v12+json,
        application/vnd.hedtech.integration.v13+json
        v3,
        v4.5.0,
        v5.0.1
        application/vnd.hedtech.integration.v3+json,
        application/vnd.hedtech.integration.v4+json,
        application/vnd.hedtech.integration.v5+json
        v2.0.1,
        v3.2.0,
        v3.0.0
        application/vnd.hedtech.integration.v2+json,
        application/vnd.hedtech.integration.v3+json
        v10.0.0,
        v11.12.0,
        v11.12.3
        application/vnd.hedtech.integration.v10+json,
        application/vnd.hedtech.integration.v11+json

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty.

        Parameters:
        resourceName - The name of the Ethos resource to get version information for.
        Returns:
        A List of Strings where each item in the list is a major version supported by the given resource.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • filterMajorVersions

        protected List<String> filterMajorVersions​(List<String> versionList)
        Intended to be used internally within the SDK.

        Filters the given versionList to remove duplicate versions and ensure each version in the returned list a major whole number version only.

        Parameters:
        versionList - A list of versions from a given resource.
        Returns:
        A list of filtered versions containing no duplicates where each version in the list is a major whole version only.

      • isResourceVersionSupported

        public boolean isResourceVersionSupported​(String resourceName,
                                          int majorVersion)
                                   throws IOException
        Indicates if the given resource supports the given major version. For example, if the resource supports this version:
        application/vnd.hedtech.integration.v12+json
        this method will return true if the major version is 12. However, if the resource only supports these versions:
        application/vnd.hedtech.integration.v12.0+json OR application/vnd.hedtech.integration.v12.0.0+json
        this method will return false.

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty.

        Parameters:
        resourceName - The name of the Ethos resource.
        majorVersion - The major version of the resource to check.
        Returns:
        true if the given resource supports the given major version, false otherwise.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • isResourceVersionSupported

        public boolean isResourceVersionSupported​(String resourceName,
                                          int majorVersion,
                                          int minorVersion)
                                   throws IOException
        Indicates if the given resource supports the given major.minor version. For example, if the resource supports this version:
        application/vnd.hedtech.integration.v12.1+json
        this method will return true if the major version is 12 and the minor version is 1. However, if the resource only supports these versions:
        application/vnd.hedtech.integration.v12.0+json OR application/vnd.hedtech.integration.v12.0.1+json
        this method will return false.

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty.

        Parameters:
        resourceName - The name of the Ethos resource.
        majorVersion - The major version of the resource to check.
        minorVersion - The minor version of the resource to check.
        Returns:
        true if the given resource supports the given major version, false otherwise.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • isResourceVersionSupported

        public boolean isResourceVersionSupported​(String resourceName,
                                          int majorVersion,
                                          int minorVersion,
                                          int patchVersion)
                                   throws IOException
        Indicates if the given resource supports the given major.minor.patch version. For example, if the resource supports this version:
        application/vnd.hedtech.integration.v12.1.0+json
        this method will return true if the major version is 12, the minor version is 1, and the patch version is 0. However, if the resource only supports these versions:
        application/vnd.hedtech.integration.v12+json OR application/vnd.hedtech.integration.v12.1+json
        this method will return false.

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty.

        Parameters:
        resourceName - The name of the Ethos resource.
        majorVersion - The major version of the resource to check.
        minorVersion - The minor version of the resource to check.
        patchVersion - The patch version of the resource to check.
        Returns:
        true if the given resource supports the given major version, false otherwise.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • isResourceVersionSupported

        public boolean isResourceVersionSupported​(String resourceName,
                                          String fullVersionHeader)
                                   throws IOException
        Indicates if the given resource supports the given full version header. The full version header should be in the following format: application/vnd.hedtech.integration.vSEMVER+json, where SEMVER is the semantic version of the requested resource.

        Also throws an IllegalArgumentException (Runtime) if the given resourceName or fullVersionHeader is null or empty.

        Parameters:
        resourceName - The name of the Ethos resource.
        fullVersionHeader - The full version header of the Ethos resource as described above.
        Returns:
        true if the given resource supports the specified full version header, false otherwise.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • isResourceVersionSupported

        public boolean isResourceVersionSupported​(String resourceName,
                                          SemVer semVer)
                                   throws IOException
        Indicates if the requested Ethos resource supports a version represented by the given SemVer object. SemVer objects are to be used where a version is truly a semantic version, and not when any of the major, minor, or patch versions of the semantic version notation are missing or not known. For example, this method should not be used when trying to determine if version 12.2 is supported because the given SemVer will translate 12.2 into 12.2.0 which is different.

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty or the given semVer is null.

        Parameters:
        resourceName - The name of the Ethos resource.
        semVer - The SemVer object containing the full semantic version to check for the resource.
        Returns:
        true if the resource supports the semantic version represented by the given semVer, false otherwise.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionHeader

        public String getVersionHeader​(String resourceName,
                               int majorVersion)
                        throws IOException
        Gets the full version header string for the given resource and major version if the resource supports the given major version. If the resource does not support the major version, an UnsupportedVersionException is thrown, which is a RuntimeException.

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty.

        Parameters:
        resourceName - The name of the resource to request the version string for.
        majorVersion - The major version of the given resource to request the full version string for.
        Returns:
        The full version string for the given resource and major version: e.g. application/vnd.hedtech.integration.v12+json
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionHeader

        public String getVersionHeader​(String resourceName,
                               int majorVersion,
                               int minorVersion)
                        throws IOException
        Gets the full version header string for the given resource, major, and minor version if the resource supports the given major.minor version. If the resource does not support the major.minor version, an UnsupportedVersionException is thrown, which is a RuntimeException.

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty.

        Parameters:
        resourceName - The name of the resource to request the version string for.
        majorVersion - The major version of the given resource to request the full version string for.
        minorVersion - The minor version of the given resource to request the full version string for.
        Returns:
        The full version string for the given resource and major.minor version: e.g. application/vnd.hedtech.integration.v12.1+json
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionHeader

        public String getVersionHeader​(String resourceName,
                               int majorVersion,
                               int minorVersion,
                               int patchVersion)
                        throws IOException
        Gets the full version header string for the given resource, major, minor, and patch version if the resource supports the given major.minor.patch version. If the resource does not support the major.minor.patch version, an UnsupportedVersionException is thrown, which is a RuntimeException.

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty.

        Parameters:
        resourceName - The name of the resource to request the version string for.
        majorVersion - The major version of the given resource to request the full version string for.
        minorVersion - The minor version of the given resource to request the full version string for.
        patchVersion - The patch version of the given resource to request the full version string for.
        Returns:
        The full version string for the given resource and major.minor.patch version: e.g. application/vnd.hedtech.integration.v12.1.3+json
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionHeader

        public String getVersionHeader​(String resourceName,
                               SemVer semVer)
                        throws IOException
        Gets the full version header string for the given resource and SemVer if the resource supports the given version contained within the SemVer. If the resource does not support the SemVer version, an UnsupportedVersionException is thrown, which is a RuntimeException.

        Also throws an IllegalArgumentException (Runtime) if the given resourceName is null or empty or the given semVer is null.

        NOTE: This method should only be used when the complete semVer notation of a version is known. For example, using the SemVer version when only the major.minor version is provided will result in a patch version of 0, which may or may not be desired.

        Parameters:
        resourceName - The name of the resource to request the version string for.
        semVer - The SemVer containing the requested version of the resource.
        Returns:
        The full version string for the given resource and major.minor.patch version: e.g. application/vnd.hedtech.integration.v12.0.0+json
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionsOfResource

        public com.fasterxml.jackson.databind.node.ArrayNode getVersionsOfResource​(String resourceName)
                                                                    throws IOException
        Gets a list of versions of the given resource name from the available-resources API. Each version in the list is from the /resource/representations/version property of the available-resources response for the given resource across all Ethos applications for the tenant in the access token. Each version value in the returned list is prefixed with the 'v' char, e.g. "v4.5.1". The returned list may contain duplicate version values.

        Each element in the returned ArrayNode contains the following properties:

        • appId - The GUID applicationId.
        • appName - The name of the application in Ethos Integration.
        • resourceName - The name of the Ethos resource.
        • versions - An array of version values, each prefixed with the 'v' char: e.g. [ "v6", "v8", "v12.1.0" ]

        The following is an example of the JSON data structure contained within the returned ArrayNode: 

         [
     {
       "appId" : "11111111-1111-1111-1111-111111111111",
       "appName" : "Banner Integration API",
       "resourceName" : "general-ledger-transactions",
       "versions" : [ "v6", "v8", "v12.1.0", "v12.0.0", "v12" ]
     }
 ]
        Parameters:
        resourceName - The resource for which to get a list of versions.
        Returns:
        A list of supported version values for the given resource.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionHeadersOfResource

        public com.fasterxml.jackson.databind.node.ArrayNode getVersionHeadersOfResource​(String resourceName)
                                                                          throws IOException
        Gets a list of full version headers of the given resource name from the available-resources API. Each version in the list is from the /resource/representations/X-Media-Type property of the available-resources response for the given resource across all Ethos applications for the tenant in the access token. An example of a full version header returned in the list is "application/vnd.hedtech.integration.v8+json". The returned list may contain duplicate version header values.

        Each element in the returned ArrayNode contains the following properties:

        • appId - The GUID applicationId.
        • appName - The name of the application in Ethos Integration.
        • resourceName - The name of the Ethos resource.
        • versions - An array of version header values: e.g. [ "application/vnd.hedtech.integration.v8+json", "application/vnd.hedtech.integration.v12.1.0+json" ]

        The following is an example of the JSON data structure contained within the returned ArrayNode: 

         [
     {
         "appId" : "11111111-1111-1111-1111-111111111111",
         "appName" : "Banner Integration API",
         "resourceName" : "general-ledger-transactions",
         "versions" : [
             "application/vnd.hedtech.integration.v6+json",
             "application/vnd.hedtech.integration.v8+json",
             "application/vnd.hedtech.integration.v12.1.0+json",
             "application/vnd.hedtech.integration.v12.0.0+json",
             "application/vnd.hedtech.integration.v12+json",
             "application/json"
         ]
     }
 ]
        Parameters:
        resourceName - The resource for which to get a list of versions.
        Returns:
        A list of supported version headers for the given resource.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionsOfResourceAsStrings

        public List<String> getVersionsOfResourceAsStrings​(String resourceName)
                                            throws IOException
        Gets a list of version string values from the /versions json property of the ArrayNode returned from getVersionsOfResource(). Version values are gathered from across Ethos Integration applications for the given tenant (access token) and resource name, and should not contain duplicate values.
        Parameters:
        resourceName - The name of the Ethos resource to get a list of versions for.
        Returns:
        A list of version strings. Each element in the list is prefixed with the 'v' char, e.g. "v4.5".
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionHeadersOfResourceAsStrings

        public List<String> getVersionHeadersOfResourceAsStrings​(String resourceName)
                                                  throws IOException
        Gets a list of version header string values from the /versions json property of the ArrayNode returned from getVersionHeadersOfResource().
        Parameters:
        resourceName - The name of the Ethos resource to get a list of version headers for.
        Returns:
        A list of version header strings.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getVersionList

        protected List<String> getVersionList​(com.fasterxml.jackson.databind.node.ArrayNode arrayNode,
                                      String representationType)
        Intended to be used internally by the SDK.

        Reads the given application/resource arrayNode and returns a simple list of version strings from that node. The given arrayNode is expected to contain an array of the following properties:

        • appId - the application ID of the app in Ethos Integration
        • appName - the name of the application in Ethos Integration
        • resourceName - the name of the Ethos resource
        • versions - a list of versions based on the representationType
        Parameters:
        arrayNode - The arrayNode containing application/resource info with a list of versions per resource.
        representationType - The JSON property to use, expected to be "/versions" when the arrayNode contains both version values (v2, v3.0.4, etc.) and version header strings.
        Returns:
        A simple list of versions from the given arrayNode, could contain duplicate version values.

      • getLatestVersion

        public String getLatestVersion​(String resourceName)
                        throws IOException
        Gets the latest version of the given resource. Could return either a Semantic version (e.g. 12.0.0), or a non-semantic version (e.g. 12), as a string value.
        Parameters:
        resourceName - The name of the resource to get the latest version of.
        Returns:
        The latest version of the given resource, either a semantic version, or a non-semantic whole number value, as a string.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getLatestVersionHeader

        public String getLatestVersionHeader​(String resourceName)
                              throws IOException
        Gets the latest version header of the given resource.
        Parameters:
        resourceName - The name of the resource to get the latest version header for.
        Returns:
        The latest full version header value of the given resource.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getFiltersAndNamedQueries

        public com.fasterxml.jackson.databind.JsonNode getFiltersAndNamedQueries​(String resourceName)
                                                                  throws IOException
        Gets a JsonNode containing the supported filters and named queries for the given resource. Uses the latest version of the resource to retrieve filters and/or named queries.
        The following is an example of the JSON data structure within the returned JsonNode: 
         {
   "resourceName" : "persons",
   "version" : "application/vnd.hedtech.integration.v12.3.0+json",
   "namedQueries" : [
       {
           "filters" : [ "personFilter" ],
           "name" : "personFilter"
       }
   ],
   "filters" : [
       "names.title",
       "names.firstName",
       "names.middleName",
       "names.lastNamePrefix",
       "names.lastName",
       "names.pedigree",
       "roles.role",
       "credentials.type",
       "credentials.value",
       "alternativeCredentials.type.id",
       "alternativeCredentials.value",
       "emails.address"
   ]
 }
        Parameters:
        resourceName - The name of the resource to get available filters and named queries for.
        Returns:
        A JsonNode containing the name of the resource and version header, with filters if they exist for the given resource and version, and/or named queries if they exist for the given resource and version.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getFiltersAndNamedQueries

        public com.fasterxml.jackson.databind.JsonNode getFiltersAndNamedQueries​(String resourceName,
                                                                         String versionHeader)
                                                                  throws IOException
        Gets a JsonNode containing the supported filters and named queries for the given resource and version header. If the given versionHeader is null or empty, the latest version will be used.
        The following is an example of the JSON data structure within the returned JsonNode: 
         {
   "resourceName" : "persons",
   "version" : "application/vnd.hedtech.integration.v12.3.0+json",
   "namedQueries" : [
       {
           "filters" : [ "personFilter" ],
           "name" : "personFilter"
       }
   ],
   "filters" : [
       "names.title",
       "names.firstName",
       "names.middleName",
       "names.lastNamePrefix",
       "names.lastName",
       "names.pedigree",
       "roles.role",
       "credentials.type",
       "credentials.value",
       "alternativeCredentials.type.id",
       "alternativeCredentials.value",
       "emails.address"
   ]
 }
        Throws an EthosResourceNotFoundException (Runtime) if the given resourceName is not found in the available-resource response.
        Parameters:
        resourceName - The name of the resource to get available filters and named queries for.
        versionHeader - The version header value used to retrieve available filters and/or named queries for the resource. If null or empty, the latest version header value will be used.
        Returns:
        A JsonNode containing the name of the resource and version header, with filters if they exist for the given resource and version, and/or named queries if they exist for the given resource and version.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getFilters

        public List<String> getFilters​(String resourceName)
                        throws IOException
        Gets a list of filters for the given resource name. The latest version of the given resource is used to obtain the list of filters.
        Parameters:
        resourceName - The name of the Ethos resource for which to get a list of filters.
        Returns:
        A list of filter values (strings) which the given resource supports, or an empty list if none found.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getFilters

        public List<String> getFilters​(String resourceName,
                               String versionHeader)
                        throws IOException
        Gets a list of filters for the given resource name and version header value.
        Parameters:
        resourceName - The name of the Ethos resource for which to get a list of filters.
        versionHeader - The full version header value for which to get a list of filters for the given resource.
        Returns:
        A list of filter values (strings) which the given resource supports, or an empty list if none found.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getNamedQueries

        public Map<String,​List<String>> getNamedQueries​(String resourceName)
                                               throws IOException
        Gets a map of named queries for the given resource name. The latest version of the given resource will be used when retrieving the named queries.

        The map keys are the names of the named queries, and the map value for each key is a list of string filter values such that: 

             Map<String,List<String>> namedQueriesMap = getNamedQueries("someResource");
     List<String> filterValuesList = namedQueriesMap.get("someNamedQuery");
     for( String filter : filterValuesList ) {
         System.out.println( String.format("FILTER: %s", filter) );
     }
        Parameters:
        resourceName - The name of the Ethos resource for which to get a map of named queries.
        Returns:
        A map of named query values (strings) which the given resource supports, or an empty map if none found. Each key in the map is the name of a named query, with a corresponding value which is a string list of filter values.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • getNamedQueries

        public Map<String,​List<String>> getNamedQueries​(String resourceName,
                                                      String versionHeader)
                                               throws IOException
        Gets a map of named queries for the given resource name and version header value. If the given version header is null or empty, the latest version of the given resource will be used.

        The map keys are the names of the named queries, and the map value for each key is a list of string filter values such that: 

             Map<String,List<String>> namedQueriesMap = getNamedQueries("someResource", "application/vnd.hedtech.integration.v8+json");
     List<String> filterValuesList = namedQueriesMap.get("someNamedQuery");
     for( String filter : filterValuesList ) {
         System.out.println( String.format("FILTER: %s", filter) );
     }
        Parameters:
        resourceName - The name of the Ethos resource for which to get a map of named queries.
        versionHeader - The full version header value for which to get a map of named queries for the given resource.
        Returns:
        A map of named query values (strings) which the given resource supports, or an empty map if none found. Each key in the map is the name of a named query, with a corresponding value which is a string list of filter values.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.

      • filterAvailableResources

        protected com.fasterxml.jackson.databind.node.ArrayNode filterAvailableResources​(com.fasterxml.jackson.databind.JsonNode availableResourcesNode,
                                                                                 com.fasterxml.jackson.databind.JsonNode desiredResourceNode)
        Intended to be used internally within the SDK.

        Filter the given list of available resources by the list of desired resources. The expected formats are:

        • availableResources - JsonNode response from calling the /admin/available-resources endpoint in Ethos Integration
        • desiredResources - JsonNode array containing objects with 'applicationId' and 'resourceName' properties. This is the format of the 'ownerOverrides' array from calling the /appConfig endpoint in Ethos Integration.
        Parameters:
        availableResourcesNode - A JsonNode containing the entire list of available resources from Ethos Integration.
        desiredResourceNode - A JsonNode containing the target list of specific app resources to be returned.
        Returns:
        An ArrayNode containing a filtered list of available resources, or an empty ArrayNode if availableResourcesNode or resourceName is null.

      • filterAvailableResources

        protected com.fasterxml.jackson.databind.node.ArrayNode filterAvailableResources​(com.fasterxml.jackson.databind.JsonNode availableResourcesNode,
                                                                                 String resourceName)
        Intended to be used internally within the SDK.

        Filter the given list of available resources by the name of the resource. The expected format of the available resources list is the JSON response from calling the /admin/available-resources endpoint in Ethos Integration. This returns an array containing the details of the given resource from each owning application in the available resources list.

        Parameters:
        availableResourcesNode - A JsonNode containing the entire list of available resources from Ethos Integration.
        resourceName - The name of the resource for which to return details.
        Returns:
        An ArrayNode containing a filtered list of available resources, or an empty ArrayNode if availableResourcesNode or resourceName is null.

      • getResourceVersionsByRepresentationType

        protected com.fasterxml.jackson.databind.node.ArrayNode getResourceVersionsByRepresentationType​(String resourceName,
                                                                                                String representationType)
                                                                                         throws IOException
        Intended to be used internally within the SDK.

        Gets an ArrayNode containing a list of objects with each element in the list having this structure:

        • appId - the application ID of the app in Ethos Integration
        • appName - the name of the application in Ethos Integration
        • resourceName - the name of the Ethos resource
        • versions - a list of versions based on the representationType

        Gets a list of versions of the given resource name from the available-resources API. Uses the representationType param to return either a list of version headers, or a list of version values. Version values are prefixed with the char 'v', e.g. v4.5.0. To return a list of version headers, the representationType must be '/X-Media-Type'. To return a list of version values, the representationType must be '/version'. A runtime IllegalArgumentException will be thrown if the resourceName param is null or empty, or if the representationType param is not one of those two supported values. Each version in the list is from the /resource/representations/X-Media-Type or the /resource/representations/version property of the available-resources response for the given resource across all Ethos applications for the tenant in the access token. The returned list may contain duplicate version values.

        Parameters:
        resourceName - The resource for which to get a list of versions.
        representationType - The jsonLabel in the available-resources response used to access the version or version header value. Expected to only be '/version' or '/X-Media-Type', otherwise an IllegalArgumentException will be thrown.
        Returns:
        A list of supported version values for the given resource according to the given representationType. If the representationType is '/X-Media-Type' a list of full version headers will be returned. If the representationType is '/version' a list of version values where each version value is prefixed with the 'v' char will be returned.
        Throws:
        IOException - Propagates this exception if it occurs when making the call in the EthosClient.