commercetools Java SDK custom types
This library extends the official commercetools Java SDK by generating custom types defined in your commercetools project. Currently, type-safe product types are supported. The goal is to support type-safe reference expansion, custom fields and even custom objects.
Why?
Accessing product attributes and custom fields with the provided tools like AttributeAccessor is not type-safe. It has no IDE support and makes your code harder to refactor. This library aims to provide types for all your custom commercetools types.
Given a product-type like this:
{
"id": "e8de347b-38fa-401d-a996-aa118658a90f",
"name": "test",
"attributes": [
{
"name": "a-boolean",
"type": {
"name": "boolean"
}
},
{
"name": "an-enum",
"type": {
"name": "enum",
"values": []
}
},
{
"name": "ref-set",
"type": {
"name": "set",
"elementType": {
"name": "reference",
"referenceTypeId": "product"
}
}
},
{
"name": "nested-second-type",
"type": {
"name": "nested",
"typeReference": {
"typeId": "product-type",
"id": "30313b5a-8573-4d3e-bfbf-566238168505"
}
}
}
]
}
the library will generate the following classes (simplified):
data class TestProduct : Product
data class TestProductCatalogData : ProductCatalogData
data class TestProductData : ProductData
data class TestProductVariant : ProductVariant
data class TestProductVariantAttributes (
var aBoolean: Boolean?,
var anEnum: AttributePlainEnumValue?,
var refSet: Set<Reference>?,
var nestedSecondType: SecondTypeProductVariantAttributes?
)
Instead of dealing with attributes like this:
fun fetchProduct(productId: String): Product
val productVariant =
fetchProduct("some-id")
.masterData
.current
.masterVariant
print(AttributeAccessor.asBoolean(productVariant.attributes[0]))
you can now easily use typed attributes:
fun fetchProduct(productId: String): Product
val productVariant =
fetchProduct("some-id")
.masterData
.current
.masterVariant
when (productVariant) {
is TestProductVariant -> print(productVariant.typedAttributes.aBoolean)
else -> TODO()
}
Since the library generates classes conforming to all API interfaces, you can start using it without the need to refactor all your existing code.
Modules
- generator - Code for generating type-safe custom types defined in commercetools projects
- gradle-plugin - Gradle Plugin that generates type-safe custom types
Usage
While the package generator is published as a stand-alone library, the most common use case is generating custom types by using the Gradle Plugin.
Gradle Plugin
The quickest way to generate custom types for your commercetools project is to simply download them. To do so, generate an API client with the scopes view_types and view_products, and then configure the plugin like this:
import de.akii.commercetools.api.customtypes.plugin.gradle.commercetoolsCustomTypes
plugins {
id("de.akii.commercetools.api.customtypes") version $pluginVersion
}
commercetoolsCustomTypes {
clientId = "
"
clientSecret = "
"
serviceRegion = "GCP_EUROPE_WEST1"
projectName = "
"
packageName = "your.types.go.here"
}
Alternatively, you can provide the product types yourself. To do so, do not specify client credentials but instead, configure the path to the product types JSON file.
import de.akii.commercetools.api.customtypes.plugin.gradle.commercetoolsCustomTypes
plugins {
id("de.akii.commercetools.api.customtypes") version $pluginVersion
}
commercetoolsCustomTypes {
productTypesFile = File("./productTypes.json")
packageName = "your.types.go.here"
}
The plugin will now automatically generate custom product types based on your product type definition.
commercetools SDK
Once you've generated your custom types, you can configure the official commercetools SDK API to use them. To do so, you need to register the generated Jackson module CustomProductApiModule.
import com.commercetools.api.defaultconfig.ApiRootBuilder import com.commercetools.api.defaultconfig.ServiceRegion import io.vrap.rmf.base.client.ResponseSerializer import io.vrap.rmf.base.client.oauth2.ClientCredentials import io.vrap.rmf.base.client.utils.json.JsonUtils import your.types.go.here.CustomProductApiModule val objectMapper = JsonUtils .createObjectMapper() .registerModule(CustomProductApiModule()) val ctApi = ApiRootBuilder.of() .defaultClient( ClientCredentials.of() .withClientId("" ) .withClientSecret("" ) .build(), ServiceRegion.GCP_EUROPE_WEST1 ) .withSerializer(ResponseSerializer.of(objectMapper)) .build("" )
For alternative ways of configuring the SDK, please consult the commercetools documentation on client customization. This library introduces no breaking changes to the API.
Contributing
To get started, please fork the repo and checkout a new branch. You can then build the library locally with Gradle.
./gradlew clean build
After you have your local branch set up, take a look at our open issues to see where you can contribute.
License
This library is licensed under the MIT license.
246 Dec 29, 2022
716 Dec 30, 2022
17 Jun 25, 2020
297 Nov 25, 2022
330 Dec 11, 2022
260 Mar 31, 2022
3 Feb 2, 2022
0 Jan 7, 2022
46 Jan 1, 2023
376 Jan 4, 2023
284 Dec 28, 2022
18 Nov 10, 2021
57 Dec 8, 2022
1 Dec 23, 2022
1.1k Jan 7, 2023
958 Dec 10, 2022
34 Nov 7, 2022
41k Jan 5, 2023
348 Oct 10, 2022
4 Nov 28, 2022