Package codes.thischwa.cf

Class CfDnsClient

java.lang.Object
codes.thischwa.cf.CfDnsClient
public class CfDnsClient extends Object
CfDnsClient is a client interface to interact with Cloudflare DNS service. It allows managing DNS records and zones within the Cloudflare system, including creating, updating, retrieving, and deleting DNS records.

Example with API token authentication (recommended): 


 // Create a new CfDnsClient instance with API token
 CfDnsClient cfDnsClient = new CfDnsClientBuilder()
     .withApiTokenAuth("your-api-token")
     .build();

 // Retrieve a zone
 ZoneEntity zone = cfDnsClient.zoneGet("example.com");
 System.out.println("Zone ID: " + zone.getId());

 // Retrieve records of a subdomain
 List<RecordEntity> records = cfDnsClient.recordList(zone, "sld");
 records.forEach(record ->
     System.out.println("Record Type: " + record.getType() + ", Value: " + record.getContent())
 );

 // Create a record for the subdomain "api"
 RecordEntity created = cfDnsClient.recordCreateSld(zone, "api", 60, RecordType.A, "192.168.1.10");
 System.out.println("Created Record ID: " + created.getId());

Example with email/key authentication (legacy): 


 CfDnsClient cfDnsClient = new CfDnsClientBuilder()
     .withEmailKeyAuth("email@example.com", "your-api-key")
     .build();

Example with exception throwing enabled: 


 // Throws exception when results are empty
 CfDnsClient cfDnsClient = new CfDnsClientBuilder()
     .withApiTokenAuth("your-api-token")
     .withEmptyResultThrowsException(true)
     .build();

Example with custom base URL: 


 CfDnsClient cfDnsClient = new CfDnsClientBuilder()
     .withApiTokenAuth("your-api-token")
     .withBaseUrl("https://custom-api.example.com")
     .build();

  • Method Details

    • groupRecordsByFqdn

      public static Map<String,List<RecordEntity>> groupRecordsByFqdn(List<RecordEntity> records)
      Groups a list of DNS records by their fully qualified domain name (FQDN).
      Parameters:
      records - A list of RecordEntity objects to be grouped by FQDN.
      Returns:
      A map where the key is the FQDN (name field) and the value is a list of RecordEntity objects that share that FQDN.

    • zone

      public ZoneOperations zone(String zoneName) throws CloudflareApiException
      Provides fluent API access to operations on a specific zone. This method returns a ZoneOperations interface that allows chaining operations on DNS records within the specified zone.

      Example: 

      
 client.zone("example.com")
       .record("api")
       .create(RecordType.A, "192.168.1.1", 60);
      Parameters:
      zoneName - the name of the DNS zone (e.g., "example.com")
      Returns:
      a ZoneOperations instance for chaining operations
      Throws:
      CloudflareApiException - if the zone cannot be found or accessed

    • zoneList

      public List<ZoneEntity> zoneList() throws CloudflareApiException
      Retrieves a list of all zones from the Cloudflare API.
      Returns:
      A list of ZoneEntity objects representing the zones retrieved from the Cloudflare API.
      Throws:
      CloudflareApiException - If an error occurs during the API request or response handling.

    • zoneList

      public List<ZoneEntity> zoneList(PagingRequest pagingRequest) throws CloudflareApiException
      Retrieves a list of all DNS zones using the provided paging request parameters.
      Parameters:
      pagingRequest - the pagination request object containing parameters for paging and filtering zone data
      Returns:
      a list of ZoneEntity objects representing the DNS zones retrieved from the API
      Throws:
      CloudflareApiException - if there is an error during the API request or response processing

    • zoneGet

      public ZoneEntity zoneGet(String name) throws CloudflareApiException
      Retrieves detailed information about a specific zone by its name.
      Parameters:
      name - The name of the zone to retrieve information for.
      Returns:
      A ZoneEntity object that contains details of the specified zone.
      Throws:
      CloudflareApiException - If an error occurs while making the API request or processing the response.

    • recordList

      public List<RecordEntity> recordList(ZoneEntity zone, String sld) throws CloudflareApiException
      Retrieves DNS records for the specified second-level domain (SLD) within a zone.
      Parameters:
      zone - the zone entity representing the DNS zone to query
      sld - the second-level domain (SLD) to filter the records
      Returns:
      a list of RecordEntity objects that match the specified SLD within the zone
      Throws:
      CloudflareNotFoundException - if the specified SLD is not found in the zone
      CloudflareApiException - if an error occurs while interacting with the Cloudflare API

    • recordList

      public List<RecordEntity> recordList(ZoneEntity zone, String sld, @Nullable @Nullable RecordType... types) throws CloudflareApiException
      Retrieves DNS records for the specified second-level domain (SLD) within a zone. Optionally filters by one or more DNS record types.
      Parameters:
      zone - The zone entity containing information about the domain zone.
      sld - The second-level domain (SLD) for which to retrieve DNS records.
      types - Optional parameter specifying one or more DNS record types to filter the results.
      Returns:
      A list of RecordEntity objects representing the DNS records for the specified domain.
      Throws:
      CloudflareNotFoundException - if the specified SLD is not found in the zone
      CloudflareApiException - if an error occurs while interacting with the Cloudflare API

    • recordList

      public List<RecordEntity> recordList(ZoneEntity zone, String sld, PagingRequest pagingRequest) throws CloudflareApiException
      Retrieves all record entities for a specific second-level domain (SLD) within a given DNS zone using the provided paging request parameters.
      Parameters:
      zone - The DNS zone entity for which the SLD records are to be fetched.
      sld - The second-level domain name for which the records are retrieved.
      pagingRequest - The paging request.
      Returns:
      A list of RecordEntity associated with the desired SLD.
      Throws:
      CloudflareApiException - If an error occurs while interacting with the Cloudflare API.

    • recordList

      public List<RecordEntity> recordList(ZoneEntity zone, RecordType... types) throws CloudflareApiException
      Retrieves a list of all DNS records for a given zone. Optionally filters by one or more DNS record types.
      Parameters:
      zone - The zone entity containing information about the domain zone.
      types - Optional parameter specifying one or more DNS record types to filter the results.
      Returns:
      A list of RecordEntity objects representing the DNS records for the specified zone.
      Throws:
      CloudflareApiException - if an error occurs while interacting with the Cloudflare API

    • recordCreateSld

      public RecordEntity recordCreateSld(ZoneEntity zone, String sld, int ttl, RecordType type, String content) throws CloudflareApiException
      Creates a new DNS record for a given second-level domain (SLD) within the specified zone.
      Parameters:
      zone - The ZoneEntity representing the DNS zone where the record is to be created.
      sld - The second-level domain (SLD) for which the DNS record is being created.
      ttl - The time-to-live (TTL) value for the DNS record in seconds.
      type - The RecordType specifying the type of the DNS record (e.g., A, AAAA, CNAME).
      content - The content of the DNS record (e.g., IP address for A/AAAA records, target domain for CNAME).
      Returns:
      The created RecordEntity object containing details of the newly created DNS record.
      Throws:
      CloudflareApiException - If an error occurs while communicating with the Cloudflare API or creating the record.

    • recordCreate

      public RecordEntity recordCreate(ZoneEntity zone, String name, int ttl, RecordType type, String content) throws CloudflareApiException
      Creates a DNS record in the specified DNS zone with the provided details.
      Parameters:
      zone - the DNS zone in which the record will be created
      name - the name of the DNS record (e.g., www.example.com)
      ttl - the time-to-live (TTL) value for the DNS record
      type - the type of the DNS record (e.g., A, AAAA, CNAME)
      content - the content or value of the DNS record
      Returns:
      the created DNS record as a RecordEntity object
      Throws:
      CloudflareApiException - if an error occurs while interacting with the Cloudflare API

    • recordCreate

      public RecordEntity recordCreate(ZoneEntity zone, RecordEntity rec) throws CloudflareApiException
      Creates a new DNS record in the specified zone using the Cloudflare API.
      Parameters:
      zone - The zone entity where the record will be created. Contains details such as zone ID.
      rec - The record entity representing the DNS record to be created, including its attributes.
      Returns:
      The created record entity as returned by the Cloudflare API.
      Throws:
      CloudflareApiException - If an error occurs while interacting with the Cloudflare API.

    • recordDelete

      public boolean recordDelete(ZoneEntity zone, RecordEntity rec) throws CloudflareApiException
      Deletes a DNS record of the specified type within a given zone on the Cloudflare API.
      Parameters:
      zone - The zone entity that specifies the zone in which the record exists.
      rec - The record entity that represents the DNS record to be deleted.
      Returns:
      true if the DNS record was successfully deleted; false otherwise.
      Throws:
      CloudflareApiException - if there is an issue during the API communication, or the request fails for any reason.

    • recordDelete

      public boolean recordDelete(ZoneEntity zone, String id) throws CloudflareApiException
      Deletes a DNS record of the specified type within a given zone on the Cloudflare API.
      Parameters:
      zone - The zone entity that specifies the zone in which the record exists.
      id - The record entity that represents the DNS record to be deleted.
      Returns:
      true if the DNS record was successfully deleted; false otherwise.
      Throws:
      CloudflareApiException - if there is an issue during the API communication or the request fails for any reason.

    • recordUpdate

      public RecordEntity recordUpdate(ZoneEntity zone, RecordEntity rec) throws CloudflareApiException
      Updates an existing DNS record in a specified Cloudflare zone.
      Parameters:
      zone - the zone entity containing the ID of the target zone
      rec - the record entity containing the ID of the DNS record to be updated and its updated data
      Returns:
      the updated record entity as returned by the Cloudflare API
      Throws:
      CloudflareApiException - if an error occurs while interacting with the Cloudflare API

    • recordDeleteTypeIfExists

      public void recordDeleteTypeIfExists(ZoneEntity zone, String sld, RecordType... recordTypes) throws CloudflareApiException
      Deletes DNS records of a specific type within a given zone if they exist. If no record of the specified type exists, it logs this occurrence without throwing an exception.
      Parameters:
      zone - The DNS zone entity in which the record exists.
      sld - The second-level domain for which the record is being checked.
      recordTypes - The types of DNS records that should be deleted if they exist.
      Throws:
      CloudflareApiException - If an error occurs during API communication.

    • recordBatch

      public BatchEntry recordBatch(ZoneEntity zone, @Nullable @Nullable List<RecordEntity> postRecords, @Nullable @Nullable List<RecordEntity> putRecords, @Nullable @Nullable List<RecordEntity> patchRecords, @Nullable @Nullable List<RecordEntity> deleteRecords) throws CloudflareApiException
      Processes a batch of DNS record operations (POST, PUT, PATCH, DELETE) for a specified zone. This method builds and cleans the input records, sends the batch request to the Cloudflare API, and returns a result containing processed batch entries.
      Parameters:
      zone - The zone entity to which the records belong.
      postRecords - A list of DNS records to be created (POST). This parameter is nullable.
      putRecords - A list of DNS records to be fully replaced (PUT). This parameter is nullable.
      patchRecords - A list of DNS records to be partially updated (PATCH). This parameter is nullable.
      deleteRecords - A list of DNS records to be deleted (DELETE). This parameter is nullable.
      Returns:
      The resulting BatchEntry containing the processed records after the batch operation.
      Throws:
      CloudflareApiException - If an error occurs while communicating with the Cloudflare API.