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.

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
• 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
• 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
• Returns:
  • A list of matching RangerPolicy objects
• 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
• 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
• 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

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