From 0f1248d08b7d9624ae456bf77cca58473303d6f9 Mon Sep 17 00:00:00 2001 From: Thilo Schwarz Date: Tue, 6 Jan 2026 20:35:50 +0100 Subject: [PATCH] issue #9: Refactor `recordGet` to `recordList` for consistency across API methods, update related documentation, and revise impacted tests. --- README.md | 59 +++++++-------- .../java/codes/thischwa/cf/CfDnsClient.java | 72 ++++++++----------- .../cf/fluent/RecordOperationsImpl.java | 5 +- .../java/codes/thischwa/cf/CfClientTest.java | 32 ++++----- 4 files changed, 77 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 87b6ad0..5edd8a3 100644 --- a/README.md +++ b/README.md @@ -55,12 +55,12 @@ The dependency is: - **Breaking Change**: `emptyResultThrowsException` default changed from `true` to `false`. Now applies to both single and multiple result requests. Empty results will be returned by default without throwing exceptions. - API method names refactored for consistency: `zoneListAll` → `zoneList`, `zoneInfo` → `zoneGet`, `sldListAll` → - `recordList`, `sldInfo` → `recordGet` + `recordList` - RecordEntity getter methods renamed for clarity: `getName()` → `getSld()` - Code quality improvements: eliminated duplication in batch operations, improved type safety in HTTP methods, optimized string concatenation, removed mutable setters from CfDnsClient - Enhanced type validation in `RecordEntity.build()` with better error messages - - CfClient#sldInfo must return multiple RecordEntries + - CfClient#recordList must return multiple RecordEntries - add a missing source jar - ResponseResultInfo#Errors: wrong object structure - changing multiple records with put, post, patch and delete for dns-records @@ -124,6 +124,9 @@ System.out.println("Zone ID: " + zone.getId()); ### `recordList` +Retrieve records for a given zone. There are two variants: + +#### List by SLD Retrieve all records for a specific second-level domain (SLD) under a given zone. - **Parameters**: @@ -139,31 +142,27 @@ records.forEach(record -> ); ``` ---- - -### `recordGet` - -Retrieve DNS record details for a specific SLD and zone, optionally filtered by record types. +#### List by Zone (optional filtering) +Retrieve DNS record details for a zone or a specific SLD, optionally filtered by record types. - **Parameters**: - `ZoneEntity zone` - The zone object. - - `String sld` - The second-level domain. - - `RecordType... types` - Optional record types to filter by (e.g., A, CNAME). If not specified, returns all record types. + - `String sld` - (Optional) The second-level domain. + - `RecordType... types` - Optional record types to filter by (e.g., A, CNAME). If not specified, returns all record types. - **Returns**: A list of `RecordEntity` objects matching the criteria. ```java // Get all records for a specific SLD -List allRecords = cfDnsClient.recordGet(zone, "www"); -allRecords.forEach(record -> - System.out.println("Type: "+record.getType()+", Content: "+record.getContent())); +List allSldRecords = cfDnsClient.recordList(zone, "www"); -// Get only A records -List aRecords = cfDnsClient.recordGet(zone, "www", RecordType.A); -System.out.println("Found "+aRecords.size() +" A records"); +// Get only A records for a specific SLD +List aSldRecords = cfDnsClient.recordList(zone, "www", RecordType.A); -// Get A and AAAA records -List ipRecords = cfDnsClient.recordGet(zone, "www", RecordType.A, RecordType.AAAA); -ipRecords.forEach(record -> System.out.println("IP Record: "+record.getContent())); +// Get all records of a zone +List allZoneRecords = cfDnsClient.recordList(zone); + +// Get only A and AAAA records of a zone +List ipZoneRecords = cfDnsClient.recordList(zone, RecordType.A, RecordType.AAAA); ``` --- @@ -263,8 +262,8 @@ Partially update existing records. **Record IDs are required** - fetch them firs ```java // Step 1: Fetch existing records to get their IDs List recordsToUpdate = new ArrayList<>(); -recordsToUpdate.add(cfDnsClient.recordGet(zone, "api",RecordType.A).get(0)); -recordsToUpdate.add(cfDnsClient.recordGet(zone, "cdn",RecordType.A).get(0)); +recordsToUpdate.add(cfDnsClient.recordList(zone, "api",RecordType.A).get(0)); +recordsToUpdate.add(cfDnsClient.recordList(zone, "cdn",RecordType.A).get(0)); // Step 2: Modify only the fields you want to update recordsToUpdate.forEach(record ->record.setContent("192.168.2.10")); @@ -281,8 +280,8 @@ Fully replace existing records. **Record IDs are required** - fetch them first: ```java // Step 1: Fetch existing records to get their IDs List recordsToReplace = new ArrayList<>(); -recordsToReplace.add(cfDnsClient.recordGet(zone, "mail",RecordType.A).get(0)); -recordsToReplace.add(cfDnsClient.recordGet(zone, "cdn",RecordType.A).get(0)); +recordsToReplace.add(cfDnsClient.recordList(zone, "mail",RecordType.A).get(0)); +recordsToReplace.add(cfDnsClient.recordList(zone, "cdn",RecordType.A).get(0)); // Step 2: Modify all fields as needed (full replacement) recordsToReplace.get(0).setContent("192.168.3.10"); @@ -302,8 +301,8 @@ Delete existing records. **Record IDs are required** - fetch them first: ```java // Step 1: Fetch existing records to get their IDs List recordsToDelete = new ArrayList<>(); -recordsToDelete.add(cfDnsClient.recordGet(zone, "cdn",RecordType.A).get(0)); -recordsToDelete.add(cfDnsClient.recordGet(zone, "mail",RecordType.A).get(0)); +recordsToDelete.add(cfDnsClient.recordList(zone, "cdn",RecordType.A).get(0)); +recordsToDelete.add(cfDnsClient.recordList(zone, "mail",RecordType.A).get(0)); // Step 2: Send batch delete request BatchEntry result = cfDnsClient.recordBatch(zone, null, null, null, recordsToDelete); @@ -322,12 +321,12 @@ List newRecords = Arrays.asList( // Fetch existing records for update/delete (IDs required) List recordsToUpdate = Arrays.asList( - cfDnsClient.recordGet(zone, "existing-api", RecordType.A).get(0) + cfDnsClient.recordList(zone, "existing-api", RecordType.A).get(0) ); recordsToUpdate.get(0).setContent("192.168.1.200"); List recordsToDelete = Arrays.asList( - cfDnsClient.recordGet(zone, "old-api", RecordType.A).get(0) + cfDnsClient.recordList(zone, "old-api", RecordType.A).get(0) ); // Execute all operations in a single batch request @@ -360,11 +359,15 @@ client.zone("example.com") .record("api") .create(RecordType.A, "192.168.1.1",60); -// Get DNS records +// Get DNS records of a subdomain List records = client.zone("example.com") .record("www", RecordType.A) .get(); +// Get all DNS records of a zone +List zoneRecords = client.zone("example.com") + .list(RecordType.A, RecordType.AAAA); + // Update a DNS record RecordEntity updated = client.zone("example.com") .record("api", RecordType.A) @@ -428,7 +431,7 @@ CfDnsClient client = new CfDnsClient(true, "email@example.com", "yourApiKey"); ```java try { - List records = cfDnsClient.recordGet(zone, "www", RecordType.A); + List records = cfDnsClient.recordList(zone, "www", RecordType.A); System.out.println("Record IP: "+records.get(0).getContent()); } catch (CloudflareApiException e) { if (e instanceof CloudflareNotFoundException) { diff --git a/src/main/java/codes/thischwa/cf/CfDnsClient.java b/src/main/java/codes/thischwa/cf/CfDnsClient.java index f71d69d..61f52df 100644 --- a/src/main/java/codes/thischwa/cf/CfDnsClient.java +++ b/src/main/java/codes/thischwa/cf/CfDnsClient.java @@ -173,21 +173,41 @@ public class CfDnsClient extends CfBasicHttpClient { } /** - * Retrieves all record entities for a specific second-level domain (SLD) within a given DNS - * zone. + * Retrieves DNS records for the specified second-level domain (SLD) within a zone. * - * @param zone The DNS zone entity for which the SLD records are to be fetched. - * @param sld The second-level domain name for which the records are retrieved. - * @return A list of {@code RecordEntity} associated with the desired SLD. - * @throws CloudflareApiException If an error occurs while interacting with the Cloudflare API. + * @param zone the zone entity representing the DNS zone to query + * @param sld the second-level domain (SLD) to filter the records + * @return 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 + * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API */ public List recordList(ZoneEntity zone, String sld) throws CloudflareApiException { - return recordList(zone, sld, PagingRequest.defaultPaging()); + return recordList(zone, sld, (RecordType[]) null); + } + + /** + * Retrieves DNS records for the specified second-level domain (SLD) within a zone. + * Optionally filters by one or more DNS record types. + * + * @param zone The zone entity containing information about the domain zone. + * @param sld The second-level domain (SLD) for which to retrieve DNS records. + * @param types Optional parameter specifying one or more DNS record types to filter the results. + * @return A list of {@code RecordEntity} objects representing the DNS records for the specified domain. + * @throws CloudflareNotFoundException if the specified SLD is not found in the zone + * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API + */ + public List recordList(ZoneEntity zone, String sld, @Nullable RecordType... types) + throws CloudflareApiException { + String fqdn = buildFqdn(zone, sld); + String endpoint = buildEndpointWithTypeFilters(CfRequest.RECORD_INFO_NAME.buildPath(zone.getId(), fqdn), types); + RecordMultipleResponse resp = getRequest(endpoint, RecordMultipleResponse.class); + checkResponse(resp, false); + return resp.getResult(); } /** * Retrieves all record entities for a specific second-level domain (SLD) within a given DNS - * zone. + * zone using the provided paging request parameters. * * @param zone The DNS zone entity for which the SLD records are to be fetched. * @param sld The second-level domain name for which the records are retrieved. @@ -205,40 +225,6 @@ public class CfDnsClient extends CfBasicHttpClient { return resp.getResult(); } - /** - * Retrieves a list of DNS record entities for a specified second-level domain (SLD) - * within a given zone. - * - * @param zone the zone entity representing the DNS zone to query - * @param sld the second-level domain (SLD) to filter the records - * @return 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 - * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API - */ - public List recordGet(ZoneEntity zone, String sld) throws CloudflareApiException { - return recordGet(zone, sld, (RecordType[]) null); - } - - /** - * Retrieves a list of DNS records for a given second-level domain (SLD) within a specific zone. - * Optionally filters by one or more DNS record types. - * - * @param zone The zone entity containing information about the domain zone. - * @param sld The second-level domain (SLD) for which to retrieve DNS records. - * @param types Optional parameter specifying one or more DNS record types to filter the results. - * @return A list of {@code RecordEntity} objects representing the DNS records for the specified domain. - * @throws CloudflareNotFoundException if the specified SLD is not found in the zone - * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API - */ - public List recordGet(ZoneEntity zone, String sld, @Nullable RecordType... types) - throws CloudflareApiException { - String fqdn = buildFqdn(zone, sld); - String endpoint = buildEndpointWithTypeFilters(CfRequest.RECORD_INFO_NAME.buildPath(zone.getId(), fqdn), types); - RecordMultipleResponse resp = getRequest(endpoint, RecordMultipleResponse.class); - checkResponse(resp, false); - return resp.getResult(); - } - /** * Retrieves a list of all DNS records for a given zone. * Optionally filters by one or more DNS record types. @@ -395,7 +381,7 @@ public class CfDnsClient extends CfBasicHttpClient { String fqdn = buildFqdn(zone, sld); List recs; try { - recs = recordGet(zone, sld, recordTypes); + recs = recordList(zone, sld, recordTypes); } catch (CloudflareNotFoundException e) { log.trace("No record of type {} found for domain {}.", recordTypes, fqdn); return; diff --git a/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java b/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java index 8021ffd..a5b08d3 100644 --- a/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java +++ b/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java @@ -35,10 +35,7 @@ public class RecordOperationsImpl implements RecordOperations { @Override public List get() throws CloudflareApiException { - if (types == null || types.length == 0) { - return client.recordGet(zone, sld); - } - return client.recordGet(zone, sld, types); + return client.recordList(zone, sld, types); } @Override diff --git a/src/test/java/codes/thischwa/cf/CfClientTest.java b/src/test/java/codes/thischwa/cf/CfClientTest.java index 2eb5bb4..4228166 100644 --- a/src/test/java/codes/thischwa/cf/CfClientTest.java +++ b/src/test/java/codes/thischwa/cf/CfClientTest.java @@ -38,7 +38,7 @@ public class CfClientTest { @Test void testUnknownSld() throws Exception { ZoneEntity zone = client.zoneGet(ZONE_STR); - assertThrows(CloudflareNotFoundException.class, () -> client.recordGet(zone, "unknown", RecordType.A)); + assertThrows(CloudflareNotFoundException.class, () -> client.recordList(zone, "unknown", RecordType.A)); } @Test @@ -56,7 +56,7 @@ public class CfClientTest { client.recordDeleteTypeIfExists(zone, SLD_STR, RecordType.A); assertThrows(CloudflareNotFoundException.class, - () -> client.recordGet(zone, SLD_STR, RecordType.A)); + () -> client.recordList(zone, SLD_STR, RecordType.A)); record = RecordEntity.build(SLD_STR + "." + ZONE_STR, RecordType.A, TTL, "127.1.0.1"); createdRecord = client.recordCreate(zone, record); @@ -125,8 +125,8 @@ public class CfClientTest { assertNotNull(createdRe1.getCreatedOn()); assertNotNull(createdRe1.getModifiedOn()); - // verify recordGet for A - List aRecords = client.recordGet(z, randomSld, RecordType.A); + // verify recordList for A + List aRecords = client.recordList(z, randomSld, RecordType.A); assertEquals(1, aRecords.size()); r = aRecords.get(0); assertEquals("130.0.0.3", r.getContent()); @@ -134,7 +134,7 @@ public class CfClientTest { // create AAAA record using recordCreateSld createdRe2 = client.recordCreateSld(z, randomSld, TTL, RecordType.AAAA, "2a0a:4cc0:c0:2e4::1"); - List aaaaRecords = client.recordGet(z, randomSld, RecordType.AAAA); + List aaaaRecords = client.recordList(z, randomSld, RecordType.AAAA); assertEquals(1, aaaaRecords.size()); r = aaaaRecords.get(0); assertEquals("2a0a:4cc0:c0:2e4::1", r.getContent()); @@ -173,13 +173,13 @@ public class CfClientTest { // update AAAA record createdRe2.setContent("2a0a:4cc0:c0:2e4::2"); client.recordUpdate(z, createdRe2); - aaaaRecords = client.recordGet(z, randomSld, RecordType.AAAA); + aaaaRecords = client.recordList(z, randomSld, RecordType.AAAA); assertEquals(1, aaaaRecords.size()); r = aaaaRecords.get(0); assertEquals("2a0a:4cc0:c0:2e4::2", r.getContent()); // verify A record still intact - aRecords = client.recordGet(z, randomSld, RecordType.A); + aRecords = client.recordList(z, randomSld, RecordType.A); assertEquals(1, aRecords.size()); r = aRecords.get(0); assertEquals("130.0.0.3", r.getContent()); @@ -187,12 +187,12 @@ public class CfClientTest { // delete AAAA record and verify it's gone assertTrue(client.recordDelete(z, createdRe2)); assertThrows(CloudflareNotFoundException.class, - () -> client.recordGet(z, randomSld, RecordType.AAAA)); + () -> client.recordList(z, randomSld, RecordType.AAAA)); // delete A record using helper and verify it's gone client.recordDeleteTypeIfExists(z, randomSld, RecordType.A); assertThrows(CloudflareNotFoundException.class, - () -> client.recordGet(z, randomSld, RecordType.A)); + () -> client.recordList(z, randomSld, RecordType.A)); } finally { // cleanup in case of failures during test try { @@ -277,7 +277,7 @@ public class CfClientTest { // Verify only the first 2 records for (int i = 0; i < 2; i++) { - List records1 = client.recordGet(zone, sldNames.get(i), RecordType.A); + List records1 = client.recordList(zone, sldNames.get(i), RecordType.A); assertEquals(1, records1.size()); assertEquals(IP_PREFIX + (i + 1), records1.get(0).getContent()); } @@ -287,7 +287,7 @@ public class CfClientTest { // Use first 2 records for PATCH List patchRecords = new ArrayList<>(); for (int i = 0; i < 2; i++) { - List records = client.recordGet(zone, sldNames.get(i), RecordType.A); + List records = client.recordList(zone, sldNames.get(i), RecordType.A); RecordEntity record = records.get(0); record.setContent(UPDATED_IP_PREFIX + (i + 1)); patchRecords.add(record); @@ -297,7 +297,7 @@ public class CfClientTest { // Verify both records were updated for (int i = 0; i < 2; i++) { - List updatedRecords = client.recordGet(zone, sldNames.get(i), RecordType.A); + List updatedRecords = client.recordList(zone, sldNames.get(i), RecordType.A); assertEquals(1, updatedRecords.size()); assertEquals(UPDATED_IP_PREFIX + (i + 1), updatedRecords.get(0).getContent()); } @@ -307,7 +307,7 @@ public class CfClientTest { // Delete first 2 records List deleteRecords = new ArrayList<>(); for (int i = 0; i < 2; i++) { - List records = client.recordGet(zone, sldNames.get(i), RecordType.A); + List records = client.recordList(zone, sldNames.get(i), RecordType.A); deleteRecords.add(records.get(0)); } @@ -317,7 +317,7 @@ public class CfClientTest { for (int i = 0; i < 2; i++) { String sldName = sldNames.get(i); assertThrows(CloudflareNotFoundException.class, - () -> client.recordGet(zone, sldName, RecordType.A)); + () -> client.recordList(zone, sldName, RecordType.A)); } } @@ -333,7 +333,7 @@ public class CfClientTest { // Now use PUT to replace them List putRecords = new ArrayList<>(); for (int i = 0; i < 2; i++) { - List records = client.recordGet(zone, sldNames.get(i), RecordType.A); + List records = client.recordList(zone, sldNames.get(i), RecordType.A); RecordEntity record = records.get(0); record.setContent(UPDATED_IP_PREFIX + (i + 1)); putRecords.add(record); @@ -342,7 +342,7 @@ public class CfClientTest { // Verify both records were updated for (int i = 0; i < 2; i++) { - List updatedRecords = client.recordGet(zone, sldNames.get(i), RecordType.A); + List updatedRecords = client.recordList(zone, sldNames.get(i), RecordType.A); assertEquals(1, updatedRecords.size()); assertEquals(UPDATED_IP_PREFIX + (i + 1), updatedRecords.get(0).getContent()); }