Java tutorial
/** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.hadoop.yarn.api; import java.io.IOException; import org.apache.hadoop.classification.InterfaceAudience.Public; import org.apache.hadoop.classification.InterfaceStability.Stable; import org.apache.hadoop.classification.InterfaceStability.Unstable; import org.apache.hadoop.yarn.api.protocolrecords.CommitResponse; import org.apache.hadoop.yarn.api.protocolrecords.ContainerUpdateRequest; import org.apache.hadoop.yarn.api.protocolrecords.ContainerUpdateResponse; import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusesRequest; import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusesResponse; import org.apache.hadoop.yarn.api.protocolrecords.IncreaseContainersResourceRequest; import org.apache.hadoop.yarn.api.protocolrecords.IncreaseContainersResourceResponse; import org.apache.hadoop.yarn.api.protocolrecords.ReInitializeContainerRequest; import org.apache.hadoop.yarn.api.protocolrecords.ReInitializeContainerResponse; import org.apache.hadoop.yarn.api.protocolrecords.ResourceLocalizationRequest; import org.apache.hadoop.yarn.api.protocolrecords.ResourceLocalizationResponse; import org.apache.hadoop.yarn.api.protocolrecords.RestartContainerResponse; import org.apache.hadoop.yarn.api.protocolrecords.RollbackResponse; import org.apache.hadoop.yarn.api.protocolrecords.SignalContainerRequest; import org.apache.hadoop.yarn.api.protocolrecords.SignalContainerResponse; import org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest; import org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest; import org.apache.hadoop.yarn.api.protocolrecords.StartContainersResponse; import org.apache.hadoop.yarn.api.protocolrecords.StopContainersRequest; import org.apache.hadoop.yarn.api.protocolrecords.StopContainersResponse; import org.apache.hadoop.yarn.api.records.Container; import org.apache.hadoop.yarn.api.records.ContainerId; import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; import org.apache.hadoop.yarn.api.records.ContainerStatus; import org.apache.hadoop.yarn.exceptions.YarnException; /** * <p>The protocol between an <code>ApplicationMaster</code> and a * <code>NodeManager</code> to start/stop and increase resource of containers * and to get status of running containers.</p> * * <p>If security is enabled the <code>NodeManager</code> verifies that the * <code>ApplicationMaster</code> has truly been allocated the container * by the <code>ResourceManager</code> and also verifies all interactions such * as stopping the container or obtaining status information for the container. * </p> */ @Public @Stable public interface ContainerManagementProtocol { /** * <p> * The <code>ApplicationMaster</code> provides a list of * {@link StartContainerRequest}s to a <code>NodeManager</code> to * <em>start</em> {@link Container}s allocated to it using this interface. * </p> * * <p> * The <code>ApplicationMaster</code> has to provide details such as allocated * resource capability, security tokens (if enabled), command to be executed * to start the container, environment for the process, necessary * binaries/jar/shared-objects etc. via the {@link ContainerLaunchContext} in * the {@link StartContainerRequest}. * </p> * * <p> * The <code>NodeManager</code> sends a response via * {@link StartContainersResponse} which includes a list of * {@link Container}s of successfully launched {@link Container}s, a * containerId-to-exception map for each failed {@link StartContainerRequest} in * which the exception indicates errors from per container and a * allServicesMetaData map between the names of auxiliary services and their * corresponding meta-data. Note: None-container-specific exceptions will * still be thrown by the API method itself. * </p> * <p> * The <code>ApplicationMaster</code> can use * {@link #getContainerStatuses(GetContainerStatusesRequest)} to get updated * statuses of the to-be-launched or launched containers. * </p> * * @param request * request to start a list of containers * @return response including conatinerIds of all successfully launched * containers, a containerId-to-exception map for failed requests and * a allServicesMetaData map. * @throws YarnException * @throws IOException */ @Public @Stable StartContainersResponse startContainers(StartContainersRequest request) throws YarnException, IOException; /** * <p> * The <code>ApplicationMaster</code> requests a <code>NodeManager</code> to * <em>stop</em> a list of {@link Container}s allocated to it using this * interface. * </p> * * <p> * The <code>ApplicationMaster</code> sends a {@link StopContainersRequest} * which includes the {@link ContainerId}s of the containers to be stopped. * </p> * * <p> * The <code>NodeManager</code> sends a response via * {@link StopContainersResponse} which includes a list of {@link ContainerId} * s of successfully stopped containers, a containerId-to-exception map for * each failed request in which the exception indicates errors from per * container. Note: None-container-specific exceptions will still be thrown by * the API method itself. <code>ApplicationMaster</code> can use * {@link #getContainerStatuses(GetContainerStatusesRequest)} to get updated * statuses of the containers. * </p> * * @param request * request to stop a list of containers * @return response which includes a list of containerIds of successfully * stopped containers, a containerId-to-exception map for failed * requests. * @throws YarnException * @throws IOException */ @Public @Stable StopContainersResponse stopContainers(StopContainersRequest request) throws YarnException, IOException; /** * <p> * The API used by the <code>ApplicationMaster</code> to request for current * statuses of <code>Container</code>s from the <code>NodeManager</code>. * </p> * * <p> * The <code>ApplicationMaster</code> sends a * {@link GetContainerStatusesRequest} which includes the {@link ContainerId}s * of all containers whose statuses are needed. * </p> * * <p> * The <code>NodeManager</code> responds with * {@link GetContainerStatusesResponse} which includes a list of * {@link ContainerStatus} of the successfully queried containers and a * containerId-to-exception map for each failed request in which the exception * indicates errors from per container. Note: None-container-specific * exceptions will still be thrown by the API method itself. * </p> * * @param request * request to get <code>ContainerStatus</code>es of containers with * the specified <code>ContainerId</code>s * @return response containing the list of <code>ContainerStatus</code> of the * successfully queried containers and a containerId-to-exception map * for failed requests. * * @throws YarnException * @throws IOException */ @Public @Stable GetContainerStatusesResponse getContainerStatuses(GetContainerStatusesRequest request) throws YarnException, IOException; /** * <p> * The API used by the <code>ApplicationMaster</code> to request for * resource increase of running containers on the <code>NodeManager</code>. * </p> * * @param request * request to increase resource of a list of containers * @return response which includes a list of containerIds of containers * whose resource has been successfully increased and a * containerId-to-exception map for failed requests. * * @throws YarnException * @throws IOException */ @Public @Unstable @Deprecated IncreaseContainersResourceResponse increaseContainersResource(IncreaseContainersResourceRequest request) throws YarnException, IOException; /** * <p> * The API used by the <code>ApplicationMaster</code> to request for * resource update of running containers on the <code>NodeManager</code>. * </p> * * @param request * request to update resource of a list of containers * @return response which includes a list of containerIds of containers * whose resource has been successfully updated and a * containerId-to-exception map for failed requests. * * @throws YarnException Exception specific to YARN * @throws IOException IOException thrown from NodeManager */ @Public @Unstable ContainerUpdateResponse updateContainer(ContainerUpdateRequest request) throws YarnException, IOException; SignalContainerResponse signalToContainer(SignalContainerRequest request) throws YarnException, IOException; /** * Localize resources required by the container. * Currently, this API only works for running containers. * * @param request Specify the resources to be localized. * @return Response that the localize request is accepted. * @throws YarnException Exception specific to YARN * @throws IOException IOException thrown from the RPC layer. */ @Public @Unstable ResourceLocalizationResponse localize(ResourceLocalizationRequest request) throws YarnException, IOException; /** * ReInitialize the Container with a new Launch Context. * @param request Specify the new ContainerLaunchContext. * @return Response that the ReInitialize request is accepted. * @throws YarnException Exception specific to YARN. * @throws IOException IOException thrown from the RPC layer. */ @Public @Unstable ReInitializeContainerResponse reInitializeContainer(ReInitializeContainerRequest request) throws YarnException, IOException; /** * Restart the container. * @param containerId Container Id. * @return Response that the restart request is accepted. * @throws YarnException Exception specific to YARN. * @throws IOException IOException thrown from the RPC layer. */ @Public @Unstable RestartContainerResponse restartContainer(ContainerId containerId) throws YarnException, IOException; /** * Rollback the Last ReInitialization if possible. * @param containerId Container Id. * @return Response that the rollback request is accepted. * @throws YarnException Exception specific to YARN. * @throws IOException IOException thrown from the RPC layer. */ @Public @Unstable RollbackResponse rollbackLastReInitialization(ContainerId containerId) throws YarnException, IOException; /** * Commit the Last ReInitialization if possible. Once the reinitialization * has been committed, It cannot be rolled back. * @param containerId Container Id. * @return Response that the commit request is accepted. * @throws YarnException Exception specific to YARN. * @throws IOException IOException thrown from the RPC layer. */ @Public @Unstable CommitResponse commitLastReInitialization(ContainerId containerId) throws YarnException, IOException; }