com.github.jamesnetherton.zulip.client.api.server.request.CreateProfileFieldApiRequest Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of zulip-java-client Show documentation
Java client for the Zulip REST API
The newest version!
package com.github.jamesnetherton.zulip.client.api.server.request;

import static com.github.jamesnetherton.zulip.client.api.server.request.ServerRequestConstants.REALM_PROFILE_FIELDS;

import com.github.jamesnetherton.zulip.client.api.core.ExecutableApiRequest;
import com.github.jamesnetherton.zulip.client.api.core.ZulipApiRequest;
import com.github.jamesnetherton.zulip.client.api.server.ProfileFieldType;
import com.github.jamesnetherton.zulip.client.api.server.response.CreateProfileFieldApiResponse;
import com.github.jamesnetherton.zulip.client.exception.ZulipClientException;
import com.github.jamesnetherton.zulip.client.http.ZulipHttpClient;
import java.util.Map;

/**
 * 
 * Zulip API request builder for creating a custom profile field.
 * 
 * 
 * This endpoint is only available to organization administrators.
 * 
 *
 * @see https://zulip.com/api/create-custom-profile-field
 */
public class CreateProfileFieldApiRequest extends ZulipApiRequest implements ExecutableApiRequest {

    public static final String NAME = "name";
    public static final String HINT = "hint";
    public static final String FIELD_TYPE = "field_type";
    public static final String FIELD_DATA = "field_data";
    public static final String DISPLAY_IN_PROFILE_SUMMARY = "display_in_profile_summary";
    public static final String REQUIRED = "required";

    /**
     * Constructs a {@link CreateProfileFieldApiRequest}.
     *
     * @param client The Zulip HTTP client
     */
    public CreateProfileFieldApiRequest(ZulipHttpClient client) {
        super(client);
    }

    /**
     * Creates a simple profile field determined by the provided {@link ProfileFieldType}.
     *
     * @param  type The field type to create
     * @param  name The name of the profile field
     * @param  hint The help text displayed against the custom field in the Zulip UI
     * @return      This {@link CreateProfileFieldApiRequest} instance
     */
    public CreateProfileFieldApiRequest withSimpleFieldType(ProfileFieldType type, String name, String hint) {
        putParam(NAME, name);
        putParam(HINT, hint);
        putParam(FIELD_TYPE, type.getId());
        return this;
    }

    /**
     * Creates a list of options profile field.
     *
     * @param  name The name of the profile field
     * @param  hint The help text displayed against the custom field in the Zulip UI
     * @param  data The map that determines the available list options and their order
     *
     *                   *              Map<String, Map<String, String>> options = new LinkedHashMap<>();
     *              Map<String, String> option = new LinkedHashMap<>();
     *              option.put("text", "Test Field");
     *              option.put("order", "1");
     *              options.put("test", option);
     *              
     *
     * @return      This {@link CreateProfileFieldApiRequest} instance
     */
    public CreateProfileFieldApiRequest withListOfOptionsFieldType(String name, String hint,
            Map> data) {
        putParam(NAME, name);
        putParam(HINT, hint);
        putParam(FIELD_TYPE, ProfileFieldType.LIST_OF_OPTIONS.getId());
        putParamAsJsonString(FIELD_DATA, data);
        return this;
    }

    /**
     * Creates a external account filed type. Zulip labels this field structure for this field type
     * as not being stable, so this API is best avoided unless you know what you are doing.
     *
     * @param  data The mao that determines the external account type configuration
     *
     *                   *              Map<String, String> externalData = new LinkedHashMap<>();
     *              externalData.put("subtype", "github");
     *              
     *
     * @return      This {@link CreateProfileFieldApiRequest} instance
     */
    public CreateProfileFieldApiRequest withExternalAccountFieldType(Map data) {
        putParam(FIELD_TYPE, ProfileFieldType.EXTERNAL_ACCOUNT.getId());
        putParamAsJsonString(FIELD_DATA, data);
        return this;
    }

    /**
     * Sets whether clients should display this profile field in a summary section of a users profile.
     *
     * @param  isDisplayInProfileSummary Whether clients should display this profile field in a summary section of a users
     *                                   profile
     * @return                           This {@link CreateProfileFieldApiRequest} instance
     */
    public CreateProfileFieldApiRequest withDisplayInProfileSummary(boolean isDisplayInProfileSummary) {
        putParam(DISPLAY_IN_PROFILE_SUMMARY, isDisplayInProfileSummary);
        return this;
    }

    /**
     * Sets whether the profile field is required.
     *
     * @param  required Whether the profile field is required
     * @return          This {@link CreateProfileFieldApiRequest} instance
     */
    public CreateProfileFieldApiRequest withRequired(boolean required) {
        putParam(REQUIRED, required);
        return this;
    }

    /**
     * Executes the Zulip API request for creating a custom profile field.
     *
     * @return                      The id of the created profile field
     * @throws ZulipClientException if the request was not successful
     */
    @Override
    public Long execute() throws ZulipClientException {
        CreateProfileFieldApiResponse response = client().post(REALM_PROFILE_FIELDS, getParams(),
                CreateProfileFieldApiResponse.class);
        return response.getId();
    }
}