VariantGroup
VariantGroup
A variant group is a collection of variants that share the same linked content types, and it lets you create entry variants on entries of those content types. The VariantGroup class builds the Content Management API requests that list variant groups and change their content type links. Use this class to
- list the variant groups of a stack
- link content types to one variant group
- unlink content types from one variant group
Call the variantGroup method of the Stack class to get an instance.
Note The Variants feature might not be available to every organization by default, as Variant Groups states.
addHeader
addHeader adds one header to every request that this VariantGroup object builds.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Names the header. |
| value (required) | String | Sets the header value. |
Returns: VariantGroup. The same variant group, for chaining.
Validation
- There is no client-side validation. addHeader stores any name and value.
- A null name or value makes execute() throw IllegalArgumentException, because Retrofit rejects a null header map entry.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addHeader stores the header on this object and sends no request.
- Every request method of VariantGroup sends the header, together with the headers that the object copied from the stack, such as api_key and authorization.
- A second call with the same name replaces the value. A name that matches a stack header, such as branch, replaces that header for this object.
- The header stays on this object only. The stack and other objects keep their own headers.
Example
Basic usage: send an extra header with each request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class AddVariantGroupHeader {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup variantGroup = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup();
variantGroup.addHeader("X-Request-Id", "list-variant-groups-01");
Response<ResponseBody> response = variantGroup.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addHeaders
addHeaders adds every entry of a map as a header of the requests that this VariantGroup object builds.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Maps each header name to its value. |
Returns: VariantGroup. The same variant group, for chaining.
Validation
- Throws NullPointerException if the map is null, because addHeaders copies its entries.
- A null name or value in the map makes execute() throw IllegalArgumentException, because Retrofit rejects a null header map entry.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addHeaders copies the entries into the headers of this object and sends no request.
- A name that already exists takes the new value. Headers that the map does not name stay as they are.
- Every request method of VariantGroup sends the headers.
- The header stays on this object only. The stack and other objects keep their own headers.
- The addHeader method adds one header at a time.
Example
Basic usage: send two extra headers with each request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class AddVariantGroupHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup variantGroup = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup();
HashMap<String, String> headers = new HashMap<>();
headers.put("X-Request-Id", "list-variant-groups-01");
headers.put("X-Client-Name", "variant-audit");
variantGroup.addHeaders(headers);
Response<ResponseBody> response = variantGroup.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParam
addParam adds one query parameter to this VariantGroup object, for the requests that send query parameters.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Names the query parameter. |
| value (required) | Object | Sets the parameter value, sent as its string form. |
Returns: VariantGroup. The same variant group, for chaining.
Validation
- There is no client-side validation. addParam stores any key and value.
- A null key or value makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map entry.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addParam stores the pair on this object and sends no request.
- Only the following requests send the stored parameters: find, linkContentTypes and unlinkContentTypes.
- Retrofit writes each value with its toString() form, so pass a String, a Boolean or a number.
- A second call with the same key replaces the value.
- The parameter stays on this object for every later request. VariantGroup has no public method that removes one, so get a new instance from the stack to start without parameters.
Example
Basic usage: include the variants of each group
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class AddVariantGroupParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup variantGroup = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup();
variantGroup.addParam("include_variant_info", true);
Response<ResponseBody> response = variantGroup.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParams
addParams adds every entry of a map as a query parameter of this VariantGroup object.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, Object> | Maps each query parameter name to its value. |
Returns: VariantGroup. The same variant group, for chaining.
Validation
- Throws NullPointerException if the map is null, because addParams copies its entries.
- A null key or value in the map makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map entry.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addParams copies the entries into the parameters of this object and sends no request.
- A key that already exists takes the new value. Parameters that the map does not name stay as they are.
- Only the following requests send the stored parameters: find, linkContentTypes and unlinkContentTypes.
- The signature names the map headers, but addParams stores its entries as query parameters, not as headers.
- The addParam method adds one parameter at a time.
Example
Basic usage: list variant groups with counts and a page size
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class AddVariantGroupParams {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup variantGroup = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup();
HashMap<String, Object> query = new HashMap<>();
query.put("include_count", true);
query.put("include_variant_count", true);
query.put("limit", 10);
variantGroup.addParams(query);
Response<ResponseBody> response = variantGroup.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}find
find lists the variant groups of the stack, with the query parameters that you add to this object.
Returns: Call<ResponseBody>. The request for all variant groups in the stack, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/variant_groups with every query parameter stored on this object, as Get all variant groups describes.
- Add query parameters with addParam or addParams before you call find. The API accepts the following parameters:
- include_count, include_variant_info and include_variant_count: add counts and variant details to the response.
- content_type: return only the groups linked to one content type.
- asc and desc: sort by created_at or name.
- limit and skip: page through the list. The SDK sets no page size, so the API applies its own.
- find ignores the UID of the instance. The response body is the raw JSON of the API.
Example
Basic usage: list the variant groups of a stack
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindVariantGroups {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup variantGroup = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup();
Response<ResponseBody> response = variantGroup.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: list the groups of one content type with their variants
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindVariantGroupsForContentType {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup variantGroup = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup()
.addParam("content_type", "<CONTENT_TYPE_UID>")
.addParam("include_variant_info", true)
.addParam("desc", "created_at");
Response<ResponseBody> response = variantGroup.find().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}linkContentTypes
linkContentTypes links one or more content types to the variant group whose UID you passed to stack.variantGroup(variantGroupUid).
| Name | Type | Description |
|---|---|---|
| contentTypeUids (required) | String... | Lists the content type UIDs to link. |
Returns: Call<ResponseBody>. The request that links the content types, sent when you call execute().
Validation
- Throws IllegalArgumentException if you pass no content type UID, because the request needs at least one.
- Throws IllegalAccessError if the instance has no variant group UID, or an empty one, because the request changes one group.
- Throws NullPointerException if you pass a null array, or if you set a null branch list with setBranches.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends PUT /v3/variant_groups/{variant_group_uid}/variants with every query parameter stored on this object, as Link content types describes.
- The SDK builds the JSON body itself, with three keys:
- uid: the variant group UID.
- branches: the branch list of this object, ["main"] unless you called setBranches.
- content_types: one object per UID that you pass, each with "status": "linked".
- The request changes only the content types that you pass. Other content types keep their link status.
Example
Basic usage: link two content types
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class LinkContentTypes {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup group = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup("<VARIANT_GROUP_UID>");
Response<ResponseBody> response = group.linkContentTypes("blog_post", "<CONTENT_TYPE_UID>").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Branches: link a content type on two branches
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class LinkContentTypesOnBranches {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup group = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup("<VARIANT_GROUP_UID>")
.setBranches("main", "<BRANCH>");
Response<ResponseBody> response = group.linkContentTypes("<CONTENT_TYPE_UID>").execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}Edge case: call linkContentTypes on an instance without a UID
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
public class LinkContentTypesWithoutUid {
public static void main(String[] args) {
Contentstack client = new Contentstack.Builder().build();
VariantGroup group = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup();
try {
group.linkContentTypes("<CONTENT_TYPE_UID>");
} catch (IllegalAccessError e) {
// Thrown before any request, because the instance holds no variant group UID
System.out.println("No variant group UID: " + e.getMessage());
}
}
}setBranches
setBranches sets the branches that linkContentTypes and unlinkContentTypes send in their request body.
| Name | Type | Description |
|---|---|---|
| branches (required) | List<String> | Lists the branch UIDs for the link requests. |
Returns: VariantGroup. The same variant group, for chaining.
Overloads
- setBranches(List<String> branches)
- setBranches(String... branches)
Validation
- There is no client-side validation of the branch names.
- The List overload stores a null list as it is, and the next link request then throws NullPointerException. The varargs overload throws NullPointerException at once for a null array.
- An invalid branch surfaces as an API error in the response when you call execute() on the link request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. setBranches replaces the branch list of this object and sends no request.
- The list starts as ["main"] on every new instance. A call replaces the whole list, so name main again if you need it.
- The link requests send the list as the branches key of their body. find does not use it.
- The List overload keeps a reference to your list, so a later change to that list reaches the next link request.
Example
Basic usage: link a content type on two branches with varargs
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class SetBranchesVarargs {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup group = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup("<VARIANT_GROUP_UID>")
.setBranches("main", "<BRANCH>");
Response<ResponseBody> response = group.linkContentTypes("<CONTENT_TYPE_UID>").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}List overload: pass the branches as a list
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;
public class SetBranchesList {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
List<String> branches = Arrays.asList("<BRANCH>");
VariantGroup group = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup("<VARIANT_GROUP_UID>")
.setBranches(branches);
Response<ResponseBody> response = group.unlinkContentTypes("<CONTENT_TYPE_UID>").execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}unlinkContentTypes
unlinkContentTypes unlinks one or more content types from the variant group whose UID you passed to stack.variantGroup(variantGroupUid).
| Name | Type | Description |
|---|---|---|
| contentTypeUids (required) | String... | Lists the content type UIDs to unlink. |
Returns: Call<ResponseBody>. The request that unlinks the content types, sent when you call execute().
Validation
- Throws IllegalArgumentException if you pass no content type UID, because the request needs at least one.
- Throws IllegalAccessError if the instance has no variant group UID, or an empty one, because the request changes one group.
- Throws NullPointerException if you pass a null array, or if you set a null branch list with setBranches.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends PUT /v3/variant_groups/{variant_group_uid}/variants with every query parameter stored on this object, as Unlink content types describes.
- The SDK builds the JSON body itself, with three keys:
- uid: the variant group UID.
- branches: the branch list of this object, ["main"] unless you called setBranches.
- content_types: one object per UID that you pass, each with "status": "unlinked".
- The request changes only the content types that you pass. Other content types keep their link status.
Example
Basic usage: unlink two content types
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class UnlinkContentTypes {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup group = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup("<VARIANT_GROUP_UID>");
Response<ResponseBody> response = group.unlinkContentTypes("blog_post", "<CONTENT_TYPE_UID>").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Branches: unlink a content type on two branches
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class UnlinkContentTypesOnBranches {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
VariantGroup group = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup("<VARIANT_GROUP_UID>")
.setBranches("main", "<BRANCH>");
Response<ResponseBody> response = group.unlinkContentTypes("<CONTENT_TYPE_UID>").execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}Edge case: call unlinkContentTypes on an instance without a UID
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
public class UnlinkContentTypesWithoutUid {
public static void main(String[] args) {
Contentstack client = new Contentstack.Builder().build();
VariantGroup group = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").variantGroup();
try {
group.unlinkContentTypes("<CONTENT_TYPE_UID>");
} catch (IllegalAccessError e) {
// Thrown before any request, because the instance holds no variant group UID
System.out.println("No variant group UID: " + e.getMessage());
}
}
}