Manage external volumes using SDK for Java - MaxCompute

Prerequisites

Before you begin, ensure that you have:

A MaxCompute project with permissions to manage volumes
An OSS bucket to use as the external storage location
(Optional) A RAM role ARN if you want to use role-based access to the OSS bucket
The odps-sdk-core dependency added to your project (see Add the dependency)

Add the dependency

Add odps-sdk-core to your Maven project:

<dependency>
  <groupId>com.aliyun.odps</groupId>
  <artifactId>odps-sdk-core</artifactId>
  <version>${Latest Version}</version>
</dependency>

Important

Replace ${Latest Version} with a specific version number in X.X.X-public format. Find all released versions in the Maven Central Repository. Use the latest version.

Create an external volume

API signatures

/**
 * Creates an external volume.
 * @param builder The parameter configuration of the volume.
 * @throws OdpsException
 */
public void create(VolumeBuilder builder) throws OdpsException

/**
 * Creates an external volume.
 *
 * @param volumeName The name of the volume.
 * @param comment
 * @param type To create a legacy volume, pass {@link Volume}.Type.Old. To create a volume for the new VolumeFS feature, pass {@link Volume}
 *        .Type.New. The VolumeFS feature can be used only after it is enabled for the project.
 * @throws OdpsException
 */
public void create(String volumeName, String comment, Volume.Type type)

/**
 * Creates an external volume.
 *
 * @param projectName The name of the project to which the destination external volume belongs.
 * @param volumeName The name of the volume to be created.
 * @param comment
 * @param type To create a legacy volume, pass {@link Volume}.Type.Old. To create a volume for the new VolumeFS feature, pass {@link Volume}
 *        .Type.New. The VolumeFS feature can be used only after it is enabled for the project.
 * @throws OdpsException
 */
public void create(String projectName, String volumeName, String comment, Volume.Type type)

/**
 * Creates a volume.
 *
 * @param projectName The name of the project to which the destination external volume belongs.
 * @param volumeName The name of the volume to be created.
 * @param comment
 * @param type To create a legacy volume, pass {@link Volume}.Type.Old. To create a volume for the new VolumeFS feature, pass {@link Volume}
 *        .Type.New. The VolumeFS feature can be used only after it is enabled for the project.
 * @param lifecycle The lifecycle.
 * @throws OdpsException
 */
public void create(String projectName, String volumeName, String comment, Volume.Type type, Long lifecycle) throws OdpsException

Parameters

Use Volumes.VolumeBuilder to configure the external volume before calling create(). The following table lists the builder methods:

Method	Required	Description
`.project(projectName)`	Yes	The name of the MaxCompute project
`.volumeName(extVolumeName)`	Yes	The name of the external volume to create
`.type(Volume.Type.EXTERNAL)`	Yes	The volume type; use `Volume.Type.EXTERNAL` for external volumes
`.extLocation(externalLocation)`	Yes	The OSS path in `oss://...` format
`.lifecycle(lifecycle)`	No	The lifecycle duration
`.comment(comment)`	No	A description for the volume
`.addProperty(Volumes.EXTERNAL_VOLUME_ROLEARN_KEY, roleArn)`	No	The RAM role ARN for accessing the OSS bucket

Example

public void createExternalVolume() throws Exception {
    String projectName = "test_project";
    String extVolumeName = "test_ext_1";
    String externalLocation = "oss://...";

    Long lifecycle;
    String comment;
    String roleArn;

    Volumes.VolumeBuilder builder = new Volumes.VolumeBuilder();

    builder.project(projectName).volumeName(extVolumeName).type(Volume.Type.EXTERNAL).extLocation(externalLocation);

    if (lifecycle != null) {
        builder.lifecycle(lifecycle);
    }

    if (comment != null) {
        builder.comment(comment);
    }

    if (roleArn != null) {
        builder.addProperty(Volumes.EXTERNAL_VOLUME_ROLEARN_KEY, roleArn);
    }

    getCurrentOdps().volumes().create(builder);
}

Get an external volume

API signatures

/**
 * Obtains the information about a specified external volume.
 *
 * @param volumeName The name of the volume.
 * @return
 */
public Volume get(String volumeName)

/**
 * Obtains the information about a specified external volume.
 *
 * @param projectName The name of the project.
 * @param volumeName  The name of the external volume.
 * @return
 */
public Volume get(String projectName, String volumeName)

Example

public Volume getVolume() {
    String projectName = "test_project";
    String extVolumeName = "test_ext_1";

    Volume volume = odps.volumes().get(projectName, extVolumeName);
    return volume;
}

List external volumes

Use an iterator to traverse all volumes in a project, with optional filtering by name.

API signatures

/**
 * Obtains an iterator for all volumes in the default project.
 *
 * @return A volume iterator.
 */
public Iterator<Volume> iterator()

/**
 * Obtains a volume iterator.
 *
 * @param projectName The name of the project.
 * @return A volume iterator.
 */
public Iterator<Volume> iterator(final String projectName)

/**
 * Obtains a volume iterator.
 *
 * @param filter The filter condition.
 * @return A volume iterator.
 */
public Iterator<Volume> iterator(final VolumeFilter filter)

/**
 * Obtains a volume iterator.
 *
 * @param projectName The name of the project.
 * @param filter The filter condition.
 * @return A volume iterator.
 */
public Iterator<Volume> iterator(final String projectName, final VolumeFilter filter)

Example

public Iterator<Volume> getVolumeIterator() {
    String projectName = "test_project";
    String extVolumeName = "test_ext_1";

    VolumeFilter volumeFilter = new VolumeFilter();
    volumeFilter.setName(extVolumeName);

    Iterator<Volume> iterator = odps.volumes().iterator(projectName, volumeFilter);
    return iterator;
}

Delete an external volume

API signatures

/**
 * Deletes an external volume.
 *
 * @param volumeName The name of the external volume.
 * @throws OdpsException
 */
public void delete(String volumeName)

/**
 * Deletes an external volume.
 *
 * @param projectName The project to which the external volume belongs.
 * @param volumeName The name of the external volume.
 * @throws OdpsException
 */
public void delete(String projectName, String volumeName)

Example

public void deleteVolume() {
    String projectName = "test_project";
    String extVolumeName = "test_ext_1";

    try {
        odps.volumes().delete(projectName, extVolumeName);
    } catch (OdpsException e) {
        throw new RuntimeException(e);
    }
}