Apache Ranger Java APIs¶

Apache Ranger provides Java library to interact with the Ranger service. This API reference provides detailed information about the Java APIs. The Java library internally invoke the Apache Ranger REST APIs.

There are few examples in the user guide.

Key Features supported by the APIs:

• Service Definition: Define and manage services (e.g., Snowflake, Databricks Unity Catalog, AWS S3, etc) within Ranger.
• Policy Administration: Create, update, and delete policies (e.g., access control rules) for services.
• Resource Management: Manage resources (e.g., files, tables, topics) within services.
• User and Group Management: Manage users and groups within the Ranger system.
• UDF Management: Create, update, and delete UDFs, including Template UDFs for row-level filters, and look up the policies that use them.

Constructors for RangerClient¶

Constructor for RangerClient using SSL configuration¶

public RangerClient(String hostName, String authType, String username, String password, String configFile)

This constructor initializes the RangerClient with the specified parameters. It creates a new instance of RangerRESTClient using the provided hostname and config file, and then initializes authentication based on the provided auth type, username, and password.

• Parameters:
  • hostName — hostname of Ranger
  • authType — auth type - Basic, Kerberos etc
  • username — username
  • password — password
  • configFile — path to config file for self-signed SSL enabled Apache Ranger

Constructor for RangerClient using Service Type¶

public RangerClient(String hostname, String authType, String username, String password, String appId, String serviceType)

This constructor initializes the RangerClient with the specified parameters. It creates a new instance of RangerRESTClient using the provided hostname and config file, and then initializes authentication based on the provided auth type, username, and password. The SSL configuration file is determined by the RangerPluginConfig based on the service type.

• Parameters:
  • hostname — hostname of Ranger
  • authType — auth type - Basic, Kerberos etc
  • username — username for connecting to Ranger
  • password — password
  • appId — application Id
  • serviceType — Ranger plugin service type e.g : s3, hive, hdfs etc

Constructor for RangerClient using RangerRESTClient¶

   public RangerClient(RangerRESTClient restClient)`

• Parameters:
  • restClient — - Ranger REST Client

Service Definition APIs¶

Create a new service definition in Apache Ranger¶

   public RangerServiceDef createServiceDef(RangerServiceDef serviceDef) throws RangerServiceException`

This method sends a POST request to the Ranger Admin server to create a new service definition. The service definition is specified by the RangerServiceDef object passed as a parameter. If the creation is successful, the method returns the created RangerServiceDef object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:

  • serviceDef — Service Definition

• Returns:

  • RangerServiceDef

• Exceptions:

  • RangerServiceException

Update an existing service definition¶

   public RangerServiceDef updateServiceDef(long serviceDefId, RangerServiceDef serviceDef) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to update an existing service definition. The service definition to be updated is identified by the serviceDefId parameter, and the new service definition details are provided in the serviceDef parameter. If the update is successful, the method returns the updated RangerServiceDef object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceDefId — service definition id
  • serviceDef — new service definition
• Returns:
  • RangerServiceDef
• Exceptions:
  • RangerServiceException

Update an existing service definition¶

   public RangerServiceDef updateServiceDef(String serviceDefName, RangerServiceDef serviceDef) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to update an existing service definition. The service definition to be updated is identified by the serviceDefName parameter, and the new service definition details are provided in the serviceDef parameter. If the update is successful, the method returns the updated RangerServiceDef object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceDefName — service definition name
  • serviceDef — new service definition
• Returns:
  • updated RangerServiceDef
• Exceptions:
  • RangerServiceException

Delete a service definition by ID¶

   public void deleteServiceDef(long serviceDefId) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing service definition. The service definition to be deleted is identified by the serviceDefId parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• serviceDefId — the ID of the service definition to be deleted
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Delete a service definition by name¶

   public void deleteServiceDef(String serviceDefName) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing service definition. The service definition to be deleted is identified by the serviceDefName parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• serviceDefName — the name of the service definition to be deleted
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Retrieve a service definition by ID¶

   public RangerServiceDef getServiceDef(long serviceDefId) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing service definition. The service definition to be retrieved is identified by the serviceDefId parameter. If the retrieval is successful, the method returns the retrieved RangerServiceDef object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• serviceDefId — the ID of the service definition to be retrieved
• Returns:
• The retrieved RangerServiceDef object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Retrieve a service definition by name¶

plaintext title="" linenums="0" public RangerServiceDef getServiceDef(String serviceDefName) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing service definition. The service definition to be retrieved is identified by the serviceDefName parameter. If the retrieval is successful, the method returns the retrieved RangerServiceDef object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• serviceDefName — the name of the service definition to be retrieved
• Returns:
• The retrieved RangerServiceDef object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Find service definitions based on filter criteria¶

   public List<RangerServiceDef> findServiceDefs(Map<String, String> filter) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to find service definitions that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter parameter. If the retrieval is successful, the method returns a list of matching RangerServiceDef objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• filter — a map of key-value pairs representing the filter criteria. See Filter keys for findServiceDefs for the supported keys, values, and pagination parameters
• Returns:
• A list of matching RangerServiceDef objects
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Create a new service in Apache Ranger¶

   public RangerService createService(RangerService service) throws RangerServiceException`

This method sends a POST request to the Ranger Admin server to create a new service. The service details are provided in the service parameter. If the creation is successful, the method returns the created RangerService object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• service — the service details to be created
• Returns:
• The created RangerService object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Update an existing service by ID¶

plaintext title="" linenums="0" public RangerService updateService(long serviceId, RangerService service) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to update an existing service. The service to be updated is identified by the serviceId parameter, and the new service details are provided in the service parameter. If the update is successful, the method returns the updated RangerService object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceId — the ID of the service to be updated
  • service — the new service details
• Returns:
  • The updated RangerService object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Update an existing service by name¶

plaintext title="" linenums="0" public RangerService updateService(String serviceName, RangerService service) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to update an existing service. The service to be updated is identified by the serviceName parameter, and the new service details are provided in the service parameter. If the update is successful, the method returns the updated RangerService object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service to be updated
  • service — the new service details
• Returns:
  • The updated RangerService object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Delete a service by ID¶

   public void deleteService(long serviceId) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing service. The service to be deleted is identified by the serviceId parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• serviceId — the ID of the service to be deleted
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Delete a service by name¶

   public void deleteService(String serviceName) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing service. The service to be deleted is identified by the serviceName parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service to be deleted
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve a service by ID¶

   public RangerService getService(long serviceId) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing service. The service to be retrieved is identified by the serviceId parameter. If the retrieval is successful, the method returns the retrieved RangerService object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceId — the ID of the service to be retrieved
• Returns:
  • The retrieved RangerService object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve a service by name¶

   public RangerService getService(String serviceName) throws RangerServiceException`

• Parameters:
  • serviceName — the name of the service to be retrieved
• Returns:
  • The retrieved RangerService object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Find services based on filter criteria¶

   public List<RangerService> findServices(Map<String, String> filter) throws RangerServiceException`

• Parameters:
  • filter — a map of key-value pairs representing the filter criteria. See Filter keys for findServices for the supported keys, values, and pagination parameters
• Returns:
  • A list of matching RangerService objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Policy APIs¶

Create a new policy in Apache Ranger¶

   public RangerPolicy createPolicy(RangerPolicy policy) throws RangerServiceException`

This method sends a POST request to the Ranger Admin server to create a new policy. The policy details are provided in the policy parameter. If the creation is successful, the method returns the created RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • policy — the policy details to be created
• Returns:
  • The created RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Update an existing policy by ID¶

   public RangerPolicy updatePolicy(long policyId, RangerPolicy policy) throws RangerServiceException`

• Parameters:
  • policyId — the ID of the policy to be updated
  • policy — the new policy details
• Returns:
  • The updated RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Update an existing policy by name¶

   public RangerPolicy updatePolicy(String serviceName, String policyName, RangerPolicy policy) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to update an existing policy. The policy to be updated is identified by the serviceName and policyName parameters, and the new policy details are provided in the policy parameter. If the update is successful, the method returns the updated RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • policyName — the name of the policy to be updated
  • policy — the new policy details
• Returns:
  • The updated RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Update an existing policy by name and security zone¶

   public RangerPolicy updatePolicyByNameAndZone(String serviceName, String policyName, String zoneName, RangerPolicy policy) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to update an existing policy. The policy to be updated is identified by the serviceName, policyName, and zoneName parameters, and the new policy details are provided in the policy parameter. If the update is successful, the method returns the updated RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • policyName — the name of the policy to be updated
  • zoneName — the name of the Security zone
  • policy — the new policy details
• Returns:
  • The updated RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Apply a policy to the service¶

   public RangerPolicy applyPolicy(RangerPolicy policy) throws RangerServiceException`

This method sends a POST request to the Ranger Admin server to apply a policy to the service. The policy to be applied is provided in the policy parameter. If the application is successful, the method returns the applied RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • policy — the policy to be applied
• Returns:
  • The applied RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Delete a policy by ID¶

   public void deletePolicy(long policyId) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing policy. The policy to be deleted is identified by the policyId parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • policyId — the ID of the policy to be deleted
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Delete a policy by name¶

   public void deletePolicy(String serviceName, String policyName) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing policy. The policy to be deleted is identified by the serviceName and policyName parameters. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • policyName — the name of the policy to be deleted
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Delete a policy by name and security zone¶

plaintext title="" linenums="0" public void deletePolicyByNameAndZone(String serviceName, String policyName, String zoneName) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing policy. The policy to be deleted is identified by the serviceName, policyName, and zoneName parameters. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • policyName — the name of the policy to be deleted
  • zoneName — the name of the Security zone
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve a policy by ID¶

   public RangerPolicy getPolicy(long policyId) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing policy. The policy to be retrieved is identified by the policyId parameter. If the retrieval is successful, the method returns the retrieved RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • policyId — the ID of the policy to be retrieved
• Returns:
  • the retrieved RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve a policy by name¶

   public RangerPolicy getPolicy(String serviceName, String policyName) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing policy. The policy to be retrieved is identified by the serviceName and policyName parameters. If the retrieval is successful, the method returns the retrieved RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • policyName — the name of the policy to be retrieved
• Returns:
  • the retrieved RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve a policy by policy name and security zone name¶

   public RangerPolicy getPolicyByNameAndZone(String serviceName, String policyName, String zoneName) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing policy. The policy to be retrieved is identified by the serviceName, policyName, and zoneName parameters. If the retrieval is successful, the method returns the retrieved RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • policyName — the name of the policy to be retrieved
  • zoneName — the name of the Security zone
• Returns:
  • the retrieved RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve all policies for a service¶

   public List<RangerPolicy> getPoliciesInService(String serviceName) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve all policies for a service. The service is identified by the serviceName parameter. If the retrieval is successful, the method returns a list of RangerPolicy objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
• Returns:
  • A list of RangerPolicy objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Find policies based on filter criteria¶

   public List<RangerPolicy> findPolicies(Map<String, String> filter) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to find policies that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter parameter. If the retrieval is successful, the method returns a list of matching RangerPolicy objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • filter — a map of key-value pairs representing the filter criteria. See Filter keys for findPolicies for the supported keys, values, and pagination parameters
• Returns:
  • A list of matching RangerPolicy objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Patch resource of a given policy -- add/remove resources¶

   public RangerPolicy patchPolicyResources(long policyId, RangerPolicy.RangerPolicyChangeRequest rangerPolicyChangeRequest) throws RangerServiceException

This method sends a PATCH request to the Ranger Admin server to update the existing resources within the Policy identified by the policyId.

• Parameters:
  • policyId - the ID of the policy to be updated
  • rangerPolicyChangeRequest - the change request to be applied to the policy. RangerPolicyChangeRequest.resourcesToAdd - new resources to be added. RangerPolicyChangeRequest.resourcesToRemove - resources to be removed.
• Returns:
• the updated RangerPolicy object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Update resource of a given policy -- add/remove resources¶

    public RangerPolicy updatePolicyResources(long policyId, Map<String, RangerPolicy.RangerPolicyResource> resourceMap) throws RangerServiceException

This method sends a PUT request to the Ranger Admin server to update the existing resources within the Policy identified by the policyId.

• Parameters:
• policyId - the ID of the policy to be updated
• resourceMap - the new resource to be updated in the Policy.
• Returns:
• the updated RangerPolicy object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Grant access to principals for resources defined in a policy identified by the policy ID.¶

   public RangerPolicy grantAccess(long policyId, List<RangerPolicy.RangerPolicyItem> policyItems,  boolean isAllowException) throws RangerServiceException`

This method sends a POST request to the Ranger Admin server to grant access within an existing policy. The policyId parameter specifies the target policy, while policyItems defines the access permissions and associated principals. If the specified principals already have some permissions, the new ones will be appended. If isAllowException parameter is set to true, the method updates the allowExceptions section of the policy instead. On success, the updated RangerPolicy object is returned. If the new policy item has properties that conflict with an existing policy for the same principal, the API will raise an exception.

• Parameters:
  • policyId — the ID of the policy to be updated
  • policyItems — the access details to be granted
  • isAllowException - if true, the policyItems will be added to the allowExceptions section within the policy
• Returns:
  • the updated RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Update access to principals in a policy identified by the policy ID.¶

   public RangerPolicy updateAccess(long policyId, List<RangerPolicy.RangerPolicyItem> policyItems, boolean isAllowException) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to update access to a policy. The policy to be updated is identified by the policyId parameter, and the access details, along with the principals, are provided in the policyItems parameter. If permissions already exist for the principals, the new ones will replace the existing ones, including the policy conditions for the same. If isAllowException is true, the policyItems will be added to the allowExceptions section within the policy. If the update is successful, the method returns the updated RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • policyId — the ID of the policy to be updated
  • policyItems — the access details to be updated
  • isAllowException - if true, the policyItems will be added to the allowExceptions section within the policy
• Returns:
  • the updated RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Delete access to principals for resources defined in a policy identified by the policy ID.¶

  public void deleteAccess(long policyId, Map<RangerPrincipal.PrincipalType, List<String>> rangerPrincipalsMap, List<String> permissions,  boolean isAllowException) throws RangerServiceException

This method sends a DELETE request to the Ranger Admin server to delete access to a policy. The policy to be updated is identified by the policyId parameter, and the principals are provided in the rangerPrincipalsMap parameter. If isAllowException is true, the principals will be removed from the allowExceptions section within the policy. To delete specific permissions, add them to the permissions list parameter. If the permission list is empty, the principal will be removed completely from the policy items. If the deletion is successful, the method returns the updated RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • policyId — the ID of the policy to be updated
  • rangerPrincipalsMap — the access principals for whom the access needs to be deleted.
  • permissions - List of permissions to be deleted for the given principals in the rangerPrincipalsMap
  • isAllowException - if true, the principals will be removed from the allowExceptions section within the policy
• Returns:
• the updated RangerPolicy object without the principals for whom the access was deleted
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Deny access to principals for resources defined in a policy identified by the policy ID.¶

   public RangerPolicy denyAccess(long policyId, List<RangerPolicy.RangerPolicyItem> policyItems, boolean isDenyException) throws RangerServiceException`

This method sends a POST request to the Ranger Admin server to add deny access to a policy. The policy to be updated is identified by the policyId parameter, and the access details, along with the principals, are provided in the policyItems parameter. If permissions already exist for the principals, the new ones will be added to the same. If isDenyException is true, the policyItems will be added to the denyExceptions section within the policy. If the update is successful, the method returns the updated RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • policyId — the ID of the policy to be updated
  • policyItems — the access details to be denied
  • isDenyException - if true, the policyItems will be added to the denyExceptions section within the policy
• Returns:
  • the updated RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Update deny access to principals for resources defined in a policy identified by the policy ID.¶

   public RangerPolicy updateDenyAccess(long policyId, List<RangerPolicy.RangerPolicyItem> policyItems, boolean isDenyException) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to update deny access within a policy. The policy to be updated is identified by the policyId parameter, and the access details, along with the principals, are provided in the policyItems parameter. If permissions already exist for the principals, the new ones will replace the existing ones. If isDenyException is true, the policyItems will be added to the denyExceptions section within the policy. If the update is successful, the method returns the updated RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • policyId — the ID of the policy to be updated
  • policyItems — the access details to be updated
  • isDenyException - if true, denyExceptions section within the policy will be updated
• Returns:
  • the updated RangerPolicy object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Delete deny access to principals for resources defined in a policy identified by the policy ID.¶

public void deleteDenyAccess(long policyId, Map<RangerPrincipal.PrincipalType, List<String>> rangerPrincipalsMap, List<String> permissions, boolean isDenyException) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete deny access within a policy. The policy to be updated is identified by the policyId parameter, while the principals are provided in the rangerPrincipalsMap parameter. If isDenyException is true, the principals will be removed from the denyExceptions section within the policy. To delete specific permissions, add them to the permissions list parameter. If the permission list is empty, the principal will be removed completely from the policy items. If the deletion is successful, the method returns the updated RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • policyId — the ID of the policy to be updated
  • rangerPrincipalsMap — the principals for whom the deny access needs to be deleted
  • permissions - List of permissions to be deleted from the given principals in the rangerPrincipalsMap
  • isDenyException - if true, denyExceptions section within the policy will be updated
• Returns:
• The updated RangerPolicy object without the principals for whom the deny access was deleted
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Add Data Masking Policy Items to an Existing Policy¶

  public RangerPolicy addDataMaskPolicyItems(long policyId, List<RangerPolicy.RangerDataMaskPolicyItem> policyItems) throws RangerServiceException

Upon successful completion, the updated RangerPolicy object is returned. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:

• policyItems — List of RangerDataMaskPolicyItem objects defining the data masking rules and principals to be added.

• policyId — The ID of the policy to be updated.
• Returns:

• The updated RangerPolicy object

• Exceptions:

• RangerServiceException — If an error occurs during the API call

Update Data Mask Policy Items for an Existing Policy¶

public RangerPolicy updateDataMaskPolicyItems(long policyId, List<RangerPolicy.RangerDataMaskPolicyItem> policyItems) throws RangerServiceException

This method sends a PUT request to the Ranger Admin server to update the data mask policy items for an existing policy identified by policyId. The provided policyItems replace the existing data mask entries for the specified principals in the policy if all conditions are met.

On successful update, the method returns the updated RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:

• policyId — The ID of the policy to be updated.

• policyItems — A list of RangerDataMaskPolicyItem objects defining the updated data mask rules and associated principals.

• Returns:

• The updated RangerPolicy object reflecting the changes.

• Exceptions:

• RangerServiceException — If an error occurs during the API call.

Remove Principals from Data Mask Policy¶

  public RangerPolicy deleteDataMaskPolicyItems(long policyId, Map<RangerPrincipal.PrincipalType, List<String>> rangerPrincipalsMap) throws RangerServiceException

On successful execution, the method returns the updated RangerPolicy object reflecting the changes. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:

• policyId — The ID of the policy from which principals should be removed.

• rangerPrincipalsMap — A map of PrincipalType to lists of principal names (users, groups, or roles) to be removed.

• Returns:

• The updated RangerPolicy object.

• Exceptions:

• RangerServiceException — If an error occurs during the API call.

Add Row Filter Policy Items to an Existing Policy¶

  public RangerPolicy addRowFilterPolicyItems(long policyId, List<RangerPolicy.RangerRowFilterPolicyItem> policyItems) throws RangerServiceException

This method sends a POST request to the Ranger Admin server to add one or more row filter policy items to an existing policy identified by policyId. The policyItems parameter contains the list of row filter rules and the associated principals to be added to the policy.

Upon successful execution, the method returns the updated RangerPolicy object reflecting the new row filter items. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:

• policyId — The ID of the policy to which the row filter items should be added.

• policyItems — A list of RangerRowFilterPolicyItem objects defining the row filter rules and associated principals.

• Returns:

• The updated RangerPolicy object with the new row filter items included.

• Exceptions:

• RangerServiceException — If an error occurs during the API call.

Update Row Filter Policy Items for an Existing Policy¶

public RangerPolicy updateRowFilterPolicyItems(long policyId, List<RangerPolicy.RangerRowFilterPolicyItem> policyItems) throws RangerServiceException

This method sends a PUT request to the Ranger Admin server to update the row filter policy items of an existing policy identified by policyId. The policyItems parameter contains the new row filter rules and associated principals to be applied.

If all conditions are met, the provided row filter policy items will replace the existing ones for the specified principals. On successful execution, the method returns the updated RangerPolicy object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:

• policyId — The ID of the policy to be updated.

• policyItems — A list of RangerRowFilterPolicyItem objects defining the updated row filter rules and associated principals.

• Returns:

• The updated RangerPolicy object reflecting the changes.

• Exceptions:

• RangerServiceException — If an error occurs during the API call.

Remove Principals from a Row Filter Policy¶

public RangerPolicy deleteRowFilterPolicyItems(long policyId, Map<RangerPrincipal.PrincipalType, List<String>> rangerPrincipalsMap) throws RangerServiceException

This method sends a DELETE request to the Ranger Admin server to remove specified principals (users, groups, or roles) from the row filter policy identified by policyId. The rangerPrincipalsMap parameter provides a mapping of principal types to lists of principal names that should be removed from the policy.

Upon successful execution, the method returns the updated RangerPolicy object reflecting the changes. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:

• policyId — The ID of the row filter policy from which principals should be removed.

• rangerPrincipalsMap — A map where the key is a PrincipalType (e.g. USER, GROUP, ROLE) and the value is a list of principal names to be removed.

• Returns:

The updated RangerPolicy object after removing the specified principals.

• Exceptions:
• RangerServiceException — If an error occurs during the API call.

Security Zone APIs¶

Create a new security zone in Apache Ranger.¶

  public RangerSecurityZone createSecurityZone(RangerSecurityZone securityZone) throws RangerServiceException

This method sends a POST request to the Ranger Admin server to create a new security zone. The security zone details are provided in the securityZone parameter. If the creation is successful, the method returns the created RangerSecurityZone object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • securityZone — the security zone details to be created
• Returns:
  • the created RangerSecurityZone object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Update an existing security zone by ID.¶

 public RangerSecurityZone updateSecurityZone(long zoneId, RangerSecurityZone securityZone) throws RangerServiceException

This method sends a PUT request to the Ranger Admin server to update an existing security zone. The security zone to be updated is identified by the zoneId parameter, and the new security zone details are provided in the securityZone parameter. If the update is successful, the method returns the updated RangerSecurityZone object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • zoneId — the ID of the security zone to be updated
  • securityZone — the new security zone details
• Returns:
  • the updated RangerSecurityZone object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Delete a security zone by ID.¶

   public void deleteSecurityZone(long zoneId) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing security zone. The security zone to be deleted is identified by the zoneId parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • zoneId — the ID of the security zone to be deleted
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Delete a security zone by name.¶

   public void deleteSecurityZone(String zoneName) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing security zone. The security zone to be deleted is identified by the zoneName parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • zoneName — the name of the security zone to be deleted
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve a security zone by ID.¶

   public RangerSecurityZone getSecurityZone(long zoneId) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing security zone. The security zone to be retrieved is identified by the zoneId parameter. If the retrieval is successful, the method returns the retrieved RangerSecurityZone object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • zoneId — the ID of the security zone to be retrieved
• Returns:
  • the retrieved RangerSecurityZone object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve a security zone by name.¶

   public RangerSecurityZone getSecurityZone(String zoneName) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing security zone. The security zone to be retrieved is identified by the zoneName parameter. If the retrieval is successful, the method returns the retrieved RangerSecurityZone object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • zoneName — the name of the security zone to be retrieved
• Returns:
  • the retrieved RangerSecurityZone object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve security zone headers based on filter criteria.¶

   public List<RangerSecurityZoneHeaderInfo> getSecurityZoneHeaders(Map<String, String> filter) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve security zone headers that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter parameter. If the retrieval is successful, the method returns a list of matching RangerSecurityZoneHeaderInfo objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • filter — a map of key-value pairs representing the filter criteria
• Returns:
  • a list of matching RangerSecurityZoneHeaderInfo objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve security zone service headers based on filter criteria.¶

   public List<RangerServiceHeaderInfo> getSecurityZoneServiceHeaders(Map<String, String> filter) throws RangerServiceException`

• Parameters:
  • filter — a map of key-value pairs representing the filter criteria
• Returns:
  • a list of matching RangerServiceHeaderInfo objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve security zone names for a resource.¶

   public Set<String> getSecurityZoneNamesForResource(String serviceName, Map<String, String> resource) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve security zone names for a resource. The service is identified by the serviceName parameter, and the resource details are provided in the resource parameter. If the retrieval is successful, the method returns a set of security zone names. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • resource — the resource details
• Returns:
  • a set of security zone names
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Find security zones based on filter criteria.¶

   public List<RangerSecurityZone> findSecurityZones(Map<String, String> filter) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to find security zones that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter parameter. If the retrieval is successful, the method returns a list of matching RangerSecurityZone objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• filter — a map of key-value pairs representing the filter criteria. See Filter keys for findSecurityZones for the supported keys and values
• Returns:
• a list of matching RangerSecurityZone objects
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Create a new security zone (version 2) in Apache Ranger.¶

   public RangerSecurityZoneV2 createSecurityZoneV2(RangerSecurityZoneV2 securityZonev2) throws RangerServiceException`

This method sends a POST request to the Ranger Admin server to create a new security zone (version 2). The security zone details are provided in the securityZonev2 parameter. If the creation is successful, the method returns the created RangerSecurityZoneV2 object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• securityZonev2 — the security zone details to be created
• Returns:
• the created RangerSecurityZoneV2 object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Update an existing security zone (version 2) by ID.¶

   public RangerSecurityZoneV2 updateSecurityZoneV2(long zoneId, RangerSecurityZoneV2 securityZoneV2) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to update an existing security zone. The security zone to be updated is identified by the zoneId parameter, and the new security zone details are provided in the securityZoneV2 parameter. If the update is successful, the method returns the updated RangerSecurityZoneV2 object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • zoneId — the ID of the security zone to be updated
  • securityZoneV2 — the new security zone details
• Returns:
• the updated RangerSecurityZoneV2 object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Retrieve a security zone (version 2) by ID.¶

   public RangerSecurityZoneV2 getSecurityZoneV2(long zoneId) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing security zone (version 2). The security zone to be retrieved is identified by the zoneId parameter. If the retrieval is successful, the method returns the retrieved RangerSecurityZoneV2 object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• zoneId — the ID of the security zone to be retrieved
• Returns:
• the retrieved RangerSecurityZoneV2 object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Retrieve a security zone (version 2) by name.¶

   public RangerSecurityZoneV2 getSecurityZoneV2(String zoneName) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing security zone (version 2). The security zone to be retrieved is identified by the zoneName parameter. If the retrieval is successful, the method returns the retrieved RangerSecurityZoneV2 object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• zoneName — the name of the security zone to be retrieved
• Returns:
• the retrieved RangerSecurityZoneV2 object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Partially update an existing security zone (version 2) by ID.¶

   public Boolean updateSecurityZoneV2Partially(long zoneId, RangerSecurityZoneV2.RangerSecurityZoneChangeRequest rangerSecurityZoneChangeRequest) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to partially update an existing security zone (version 2). The security zone to be updated is identified by the zoneId parameter, and the changes are provided in the rangerSecurityZoneChangeRequest parameter. If the update is successful, the method returns a Boolean indicating the success of the operation. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • zoneId — the ID of the security zone to be updated
  • rangerSecurityZoneChangeRequest — the changes to be applied to the security zone
• Returns:
• a Boolean indicating the success of the operation
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Delete a security zone (version 2) by ID.¶

   public void deleteSecurityZoneV2(long id) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing security zone (version 2). The security zone to be deleted is identified by the id parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• id — the ID of the security zone to be deleted
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Role APIs¶

Create a new role in Apache Ranger.¶

   public RangerRole createRole(String serviceName, RangerRole role) throws RangerServiceException`

This method sends a POST request to the Ranger Admin server to create a new role. The role details are provided in the role parameter. If the creation is successful, the method returns the created RangerRole object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • role — the role details to be created
• Returns:
• the created RangerRole object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Update an existing role by ID.¶

   public RangerRole updateRole(long roleId, RangerRole role) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to update an existing role. The role to be updated is identified by the roleId parameter, and the new role details are provided in the role parameter. If the update is successful, the method returns the updated RangerRole object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • roleId — the ID of the role to be updated
  • role — the new role details
• Returns:
• the updated RangerRole object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Delete a role by ID.¶

   public void deleteRole(long roleId) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing role. The role to be deleted is identified by the roleId parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• roleId — the ID of the role to be deleted
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Delete a role by name.¶

   public void deleteRole(String roleName, String execUser, String serviceName) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete an existing role. The role to be deleted is identified by the roleName parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • roleName — the name of the role to be deleted
  • execUser — the user executing the request
  • serviceName — the name of the service
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Retrieve a role by ID.¶

   public RangerRole getRole(long roleId) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing role. The role to be retrieved is identified by the roleId parameter. If the retrieval is successful, the method returns the retrieved RangerRole object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• roleId — the ID of the role to be retrieved
• Returns:
• the retrieved RangerRole object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Retrieve a role by name.¶

   public RangerRole getRole(String roleName, String execUser, String serviceName) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve an existing role. The role to be retrieved is identified by the roleName parameter. If the retrieval is successful, the method returns the retrieved RangerRole object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • roleName — the name of the role to be retrieved
  • execUser — the user executing the request
  • serviceName — the name of the service
• Returns:
• The retrieved RangerRole object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Retrieve all role names for a service.¶

   public List<String> getAllRoleNames(String execUser, String serviceName) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve all role names for a service. The service is identified by the serviceName parameter. If the retrieval is successful, the method returns a list of role names. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • execUser — the user executing the request
  • serviceName — the name of the service
• Returns:
• a list of role names
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Retrieve roles for a user.¶

   public List<String> getUserRoles(String user) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve roles for a user. The user is identified by the user parameter. If the retrieval is successful, the method returns a list of roles. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• user — the user whose roles are to be retrieved
• Returns:
• a list of roles
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Find roles based on filter criteria.¶

   public List<RangerRole> findRoles(Map<String, String> filter) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to find roles that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter parameter. If the retrieval is successful, the method returns a list of matching RangerRole objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• filter — a map of key-value pairs representing the filter criteria. See Filter keys for findRoles for the supported keys, values, and pagination parameters
• Returns:
• a list of matching RangerRole objects
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Grant a role to a user or group.¶

   public RESTResponse grantRole(String serviceName, GrantRevokeRoleRequest request) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to grant a role to a user or group. The role details are provided in the request parameter. If the grant is successful, the method returns a RESTResponse object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • request — the role grant request details
• Returns:
• a RESTResponse object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Revoke a role from a user or group.¶

   public RESTResponse revokeRole(String serviceName, GrantRevokeRoleRequest request) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to revoke a role from a user or group. The role details are provided in the request parameter. If the revoke is successful, the method returns a RESTResponse object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • request — the role revoke request details
• Returns:
• a RESTResponse object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

UDF APIs¶

These methods manage the UDF catalog of a service. A RangerUdf has a udfType: RangerUdf.UDF_TYPE_MASTER (1), RangerUdf.UDF_TYPE_SUB (2), or RangerUdf.UDF_TYPE_TEMPLATE (3). For how Master and Sub UDFs are used in row filters, see Use Reusable UDF for Row-level Filter. The methods call the /service/public/v2/api/udf endpoints of the Apache Ranger REST API.

Methods that create, update, or delete a UDF require the ROLE_SYS_ADMIN role. Read methods also accept ROLE_ADMIN_AUDITOR. An unknown UDF ID, or a service and UDF name that do not resolve, makes Ranger Admin return HTTP 400, not 404, so the get, update, delete, Sub UDF, policy, condition, and version-snapshot methods throw a RangerServiceException with status 400. The search methods return an empty list instead, and getUdfVersionList returns an empty String.

RangerUdf fields:

Template UDFs. A Template UDF (udfType = 3) is a row-filter body with one block per named condition. Each name in conditionNames must start with CONDITION followed only by uppercase letters, digits, _, or -, for example CONDITION_A. Parameter names must be unique, ignoring case. The udfText must contain ${ALL_PRINCIPAL_LIST} and exactly one <NAME>...</NAME> block for each entry in conditionNames, with no undeclared blocks. Each block must contain ${PRINCIPAL_LIST} exactly once, and the body must use every parameter name. A body that breaks these rules is rejected with HTTP 400 and error code TEMPLATE_BODY_INVALID. While any policy uses a template, renaming it, changing its parameters (other than the letter case of a name or type), removing a condition that a policy uses, or changing its udfType is rejected with HTTP 400 and error code TEMPLATE_IN_USE. Adding a condition with its block, changing description, or editing the body without changing its blocks is allowed. For how a row-filter policy references a template, see Create a Template UDF and use it in a row-filter policy.

The Template UDF fields, getConditionsForUdf, getConditionsForUdfByServiceAndName, and the error-detail methods on RangerServiceException need the ranger-intg and ranger-plugins-common libraries from a release that supports Template UDFs. Use both libraries from the same release.

Create a UDF¶

   public RangerUdf createUdf(RangerUdf udf) throws RangerServiceException

This method sends a POST request to the Ranger Admin server to create a UDF. The UDF details are provided in the udf parameter. serviceName, name, and udfText are required, and the name must be unique within the service. If the creation is successful, the method returns the created RangerUdf object with its id. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udf — the UDF to be created
• Returns:
  • The created RangerUdf object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call, for example a duplicate name or an invalid Template UDF body

Create several UDFs¶

   public List<RangerUdf> createUdfs(List<RangerUdf> udfs) throws RangerServiceException

This method sends a POST request to the Ranger Admin server to create several UDFs in one transaction. All the UDFs must belong to the same service, and none of them may have the name of an existing UDF. If any UDF is invalid, none of them is created. If the creation is successful, the method returns the created RangerUdf objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udfs — the UDFs to be created
• Returns:
  • A list of the created RangerUdf objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Create or update a UDF by service name and UDF name¶

   public RangerUdf createOrUpdateUdf(String serviceName, String udfName, RangerUdf udf) throws RangerServiceException

This method sends a PUT request to the Ranger Admin server. If the service has no UDF named udfName, the UDF is created; otherwise the existing UDF is updated. The serviceName and udfName parameters identify the UDF. If udf also sets serviceName or name, they must match these parameters. If the call is successful, the method returns the created or updated RangerUdf object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • udfName — the name of the UDF
  • udf — the UDF details
• Returns:
  • The created or updated RangerUdf object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Update a UDF by ID¶

   public RangerUdf updateUdf(long udfId, RangerUdf udf) throws RangerServiceException

This method sends a PUT request to the Ranger Admin server to replace an existing UDF. The UDF to be updated is identified by the udfId parameter, and the new UDF details are provided in the udf parameter. Send the whole UDF, including serviceName, name, and udfText, for example by changing the object returned by getUdf. The udfId parameter takes precedence over any id set in udf. If the update is successful, the method returns the updated RangerUdf object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udfId — the ID of the UDF to be updated
  • udf — the new UDF details
• Returns:
  • The updated RangerUdf object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call, for example a stale version (HTTP 409) or a locked change to a Template UDF that policies use (TEMPLATE_IN_USE)

Retrieve a UDF by ID¶

   public RangerUdf getUdf(long udfId) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve a UDF. The UDF is identified by the udfId parameter. If the retrieval is successful, the method returns the RangerUdf object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udfId — the ID of the UDF to be retrieved
• Returns:
  • The retrieved RangerUdf object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve a UDF by service name and UDF name¶

   public RangerUdf getUdfByServiceAndName(String serviceName, String udfName) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve a UDF. The UDF is identified by the serviceName and udfName parameters. If the retrieval is successful, the method returns the RangerUdf object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • udfName — the name of the UDF to be retrieved
• Returns:
  • The retrieved RangerUdf object
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Delete a UDF by ID¶

   public void deleteUdf(long udfId) throws RangerServiceException

This method sends a DELETE request to the Ranger Admin server to delete a UDF. The UDF to be deleted is identified by the udfId parameter. The deletion is rejected with HTTP 409 while any policy references the UDF, or while the UDF is linked as a Sub UDF of any Master UDF. Deleting a Master UDF removes its links to its Sub UDFs but keeps the Sub UDFs. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udfId — the ID of the UDF to be deleted
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Delete a UDF by service name and UDF name¶

   public void deleteUdfByServiceAndName(String serviceName, String udfName) throws RangerServiceException

This method sends a DELETE request to the Ranger Admin server to delete a UDF. The UDF to be deleted is identified by the serviceName and udfName parameters. The same rules apply as for deleteUdf(long udfId). If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • udfName — the name of the UDF to be deleted
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Find UDFs across all services¶

   public List<RangerUdf> findAllUdfs(Map<String, String> filter) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to find the UDFs of every service that match the filter criteria, ordered by service name and then UDF name. The filter criteria are provided as a map of key-value pairs in the filter parameter. If the retrieval is successful, the method returns a list of matching RangerUdf objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • filter — a map of key-value pairs representing the filter criteria. See Filter keys for UDF searches for the supported keys, values, and pagination parameters
• Returns:
  • A list of matching RangerUdf objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Find UDFs of a service¶

   public List<RangerUdf> getUdfsForService(String serviceName, Map<String, String> filter) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to find the UDFs of one service that match the filter criteria. The service is identified by the serviceName parameter, and the filter criteria are provided in the filter parameter. For example, set udfType to 3 to list only Template UDFs. The results are ordered by UDF name, and the list is empty when the service does not exist. If the retrieval is successful, the method returns a list of matching RangerUdf objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • filter — a map of key-value pairs representing the filter criteria. See Filter keys for UDF searches for the supported keys, values, and pagination parameters
• Returns:
  • A list of matching RangerUdf objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Find UDFs by exact name across services¶

   public List<RangerUdf> getUdfsByExactName(String udfName, Map<String, String> filter) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to find every UDF, in any service, whose name is exactly udfName. The filter parameter accepts the pagination and sort keys only. The list is empty when no UDF has that name. If the retrieval is successful, the method returns a list of matching RangerUdf objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udfName — the exact name of the UDF
  • filter — a map of pagination and sort keys, or null. See Filter keys for UDF searches
• Returns:
  • A list of matching RangerUdf objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve the Sub UDFs of a Master UDF by ID¶

   public List<RangerUdf> getSubUdfs(long udfId, Map<String, String> filter) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve the Sub UDFs linked to a Master UDF. The Master UDF is identified by the udfId parameter. The filter parameter accepts the pagination and sort keys only. The list is empty when the UDF has no Sub UDFs or is not a Master UDF. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udfId — the ID of the Master UDF
  • filter — a map of pagination and sort keys, or null. See Filter keys for UDF searches
• Returns:
  • A list of the linked Sub RangerUdf objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve the Sub UDFs of a Master UDF by service name and UDF name¶

   public List<RangerUdf> getSubUdfsByServiceAndName(String serviceName, String udfName, Map<String, String> filter) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve the Sub UDFs linked to a Master UDF. The Master UDF is identified by the serviceName and udfName parameters. It returns the same result as getSubUdfs(long udfId, Map<String, String> filter). If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • udfName — the name of the Master UDF
  • filter — a map of pagination and sort keys, or null
• Returns:
  • A list of the linked Sub RangerUdf objects
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve the policies that reference a UDF by ID¶

   public List<Map<String, Object>> getPoliciesForUdf(long udfId) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve the policies that reference a UDF. The UDF is identified by the udfId parameter. Each map in the returned list has two entries: policyId and policyName. A UDF can be deleted only when this list is empty. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udfId — the ID of the UDF
• Returns:
  • A list of maps, each with the policyId and policyName of a referencing policy
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve the policies that reference a UDF by service name and UDF name¶

   public List<Map<String, Object>> getPoliciesForUdfByServiceAndName(String serviceName, String udfName) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve the policies that reference a UDF. The UDF is identified by the serviceName and udfName parameters. It returns the same result as getPoliciesForUdf(long udfId). If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • udfName — the name of the UDF
• Returns:
  • A list of maps, each with the policyId and policyName of a referencing policy
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve the condition names of a Template UDF by ID¶

   public List<String> getConditionsForUdf(long udfId) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve the conditionNames of a Template UDF, in the order they are declared. The UDF is identified by the udfId parameter. The list is empty for a UDF that is not a Template UDF. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udfId — the ID of the Template UDF
• Returns:
  • The list of condition names
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve the condition names of a Template UDF by service name and UDF name¶

   public List<String> getConditionsForUdfByServiceAndName(String serviceName, String udfName) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve the conditionNames of a Template UDF. The UDF is identified by the serviceName and udfName parameters. It returns the same result as getConditionsForUdf(long udfId). If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • udfName — the name of the Template UDF
• Returns:
  • The list of condition names
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve the version history of a UDF by ID¶

   public String getUdfVersionList(long udfId) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve the recorded version numbers of a UDF. The UDF is identified by the udfId parameter. A version is recorded on every create, update, and delete. The method returns the version numbers as a comma-separated String, for example 1,2,3. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udfId — the ID of the UDF
• Returns:
  • The version numbers as a comma-separated String
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve the version history of a UDF by service name and UDF name¶

   public String getUdfVersionListByServiceAndName(String serviceName, String udfName) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve the recorded version numbers of a UDF. The UDF is identified by the serviceName and udfName parameters. It returns the same result as getUdfVersionList(long udfId). If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • udfName — the name of the UDF
• Returns:
  • The version numbers as a comma-separated String
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve a UDF at a given version by ID¶

   public RangerUdf getUdfForVersionNumber(long udfId, int versionNo) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve a UDF as it was at a given version. The UDF is identified by the udfId parameter, and the version by the versionNo parameter. If the retrieval is successful, the method returns the RangerUdf snapshot. An unknown version returns HTTP 400. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • udfId — the ID of the UDF
  • versionNo — a version number returned by getUdfVersionList
• Returns:
  • The RangerUdf object as it was at that version
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Retrieve a UDF at a given version by service name and UDF name¶

   public RangerUdf getUdfForVersionNumberByServiceAndName(String serviceName, String udfName, int versionNo) throws RangerServiceException

This method sends a GET request to the Ranger Admin server to retrieve a UDF as it was at a given version. The UDF is identified by the serviceName and udfName parameters, and the version by the versionNo parameter. It returns the same result as getUdfForVersionNumber(long udfId, int versionNo). If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • udfName — the name of the UDF
  • versionNo — a version number returned by getUdfVersionListByServiceAndName
• Returns:
  • The RangerUdf object as it was at that version
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Download the UDF catalog of a service¶

   public RangerUdfs downloadUdfsIfUpdated(String serviceName, Map<String, String> queryParams) throws RangerServiceException
   public RangerUdfs downloadUdfsIfUpdatedSecure(String serviceName, Map<String, String> queryParams) throws RangerServiceException

These methods send a GET request to the Ranger Admin server to download the full UDF catalog of a service, as a plugin does. downloadUdfsIfUpdatedSecure calls the secure download endpoint, which plugins use over HTTPS or Kerberos. The service is identified by the serviceName parameter. The queryParams parameter accepts lastKnownUdfVersion (-1 forces a full download), lastActivationTime, pluginId, clusterName, and pluginCapabilities. The methods return a RangerUdfs object with the catalog, or null when the catalog has not changed since lastKnownUdfVersion (HTTP 304) or Ranger Admin is unavailable (HTTP 503). An unknown service returns HTTP 404. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • queryParams — the download parameters listed above
• Returns:
  • A RangerUdfs object, or null if the catalog has not changed or Ranger Admin is unavailable
• Exceptions:
  • RangerServiceException — If an error occurs during the API call

Error details on RangerServiceException¶

When Ranger Admin rejects a request, RangerServiceException exposes the parsed error response in addition to getStatus(). Check the error code instead of the message text, because the message wording can change.

Template UDF requests and policies that reference a Template UDF can fail with these error codes, all with HTTP 400:

Deleting a UDF that policies reference, and updating a UDF with a stale version, fail with HTTP 409 and no error code, so check getStatus() for those cases.

User and Group APIs¶

Find users based on filter criteria.¶

   public String findUsers(Map<String, String> filter) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to find users that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter parameter. If the retrieval is successful, the method returns the raw JSON response, whose vXUsers array holds the matching users. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• filter — a map of key-value pairs representing the filter criteria. See Filter keys for findUsers and findGroups for the supported keys, values, and pagination parameters
• Returns:
• the JSON response as a String
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Find groups based on filter criteria.¶

   public String findGroups(Map<String, String> filter) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to find groups that match the specified filter criteria. The filter criteria are provided as a map of key-value pairs in the filter parameter. If the retrieval is successful, the method returns the raw JSON response, whose vXGroups array holds the matching groups. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• filter — a map of key-value pairs representing the filter criteria. See Filter keys for findUsers and findGroups for the supported keys, values, and pagination parameters
• Returns:
• the JSON response as a String
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Import service tags into Apache Ranger.¶

   public void importServiceTags(String serviceName, RangerServiceTags svcTags) throws RangerServiceException`

This method sends a PUT request to the Ranger Admin server to import service tags. The service is identified by the serviceName parameter, and the tags to be imported are provided in the svcTags parameter. If the import is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • serviceName — the name of the service
  • svcTags — the service tags to be imported
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Retrieve service tags from Apache Ranger.¶

   public RangerServiceTags getServiceTags(String serviceName) throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve service tags. The service is identified by the serviceName parameter. If the retrieval is successful, the method returns the retrieved RangerServiceTags object. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
• serviceName — the name of the service
• Returns:
• The retrieved RangerServiceTags object
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Retrieve plugin information from Apache Ranger.¶

   public List<RangerPluginInfo> getPluginsInfo() throws RangerServiceException`

This method sends a GET request to the Ranger Admin server to retrieve plugin information. If the retrieval is successful, the method returns a list of RangerPluginInfo objects. If an error occurs during the API call, a RangerServiceException is thrown.

• Returns:
• a list of RangerPluginInfo objects
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Delete policy deltas from Apache Ranger.¶

   public void deletePolicyDeltas(int days, boolean reloadServicePoliciesCache) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to delete policy deltas. The number of days to retain is specified by the days parameter, and whether to reload the service policies cache is specified by the reloadServicePoliciesCache parameter. If the deletion is successful, the method completes without returning any value. If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • days — the number of days to retain
  • reloadServicePoliciesCache — whether to reload the service policies cache
• Exceptions:
• RangerServiceException — If an error occurs during the API call

Purge records from Apache Ranger.¶

   public List<RangerPurgeResult> purgeRecords(String recordType, int retentionDays) throws RangerServiceException`

This method sends a DELETE request to the Ranger Admin server to purge records. The type of records to purge is specified by the recordType parameter, and the retention period is specified by the retentionDays parameter. The recordType parameter can be one of the following: login_records, trx_records, policy_export_logs If the purge is successful, the method returns a list of RangerPurgeResult objects. T If an error occurs during the API call, a RangerServiceException is thrown.

• Parameters:
  • recordType — the type of records to purge
  • retentionDays — the retention period in days
• Returns: a list of
• RangerPurgeResult objects
• Exceptions:
• RangerServiceException — If an error occurs during the API call