001/**
002* Licensed to the Apache Software Foundation (ASF) under one
003* or more contributor license agreements.  See the NOTICE file
004* distributed with this work for additional information
005* regarding copyright ownership.  The ASF licenses this file
006* to you under the Apache License, Version 2.0 (the
007* "License"); you may not use this file except in compliance
008* with the License.  You may obtain a copy of the License at
009*
010*     http://www.apache.org/licenses/LICENSE-2.0
011*
012* Unless required by applicable law or agreed to in writing, software
013* distributed under the License is distributed on an "AS IS" BASIS,
014* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015* See the License for the specific language governing permissions and
016* limitations under the License.
017*/
018
019package org.apache.hadoop.yarn.api.records;
020
021import org.apache.hadoop.classification.InterfaceAudience.Private;
022import org.apache.hadoop.classification.InterfaceAudience.Public;
023import org.apache.hadoop.classification.InterfaceStability.Stable;
024import org.apache.hadoop.classification.InterfaceStability.Unstable;
025import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
026import org.apache.hadoop.yarn.api.ContainerManagementProtocol;
027import org.apache.hadoop.yarn.util.Records;
028
029/**
030 * {@code Container} represents an allocated resource in the cluster.
031 * <p>
032 * The {@code ResourceManager} is the sole authority to allocate any
033 * {@code Container} to applications. The allocated {@code Container}
034 * is always on a single node and has a unique {@link ContainerId}. It has
035 * a specific amount of {@link Resource} allocated.
036 * <p>
037 * It includes details such as:
038 * <ul>
039 *   <li>{@link ContainerId} for the container, which is globally unique.</li>
040 *   <li>
041 *     {@link NodeId} of the node on which it is allocated.
042 *   </li>
043 *   <li>HTTP uri of the node.</li>
044 *   <li>{@link Resource} allocated to the container.</li>
045 *   <li>{@link Priority} at which the container was allocated.</li>
046 *   <li>
047 *     Container {@link Token} of the container, used to securely verify
048 *     authenticity of the allocation.
049 *   </li>
050 * </ul>
051 * 
052 * Typically, an {@code ApplicationMaster} receives the {@code Container}
053 * from the {@code ResourceManager} during resource-negotiation and then
054 * talks to the {@code NodeManager} to start/stop containers.
055 * 
056 * @see ApplicationMasterProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest)
057 * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest)
058 * @see ContainerManagementProtocol#stopContainers(org.apache.hadoop.yarn.api.protocolrecords.StopContainersRequest)
059 */
060@Public
061@Stable
062public abstract class Container implements Comparable<Container> {
063
064  @Private
065  @Unstable
066  public static Container newInstance(ContainerId containerId, NodeId nodeId,
067      String nodeHttpAddress, Resource resource, Priority priority,
068      Token containerToken) {
069    Container container = Records.newRecord(Container.class);
070    container.setId(containerId);
071    container.setNodeId(nodeId);
072    container.setNodeHttpAddress(nodeHttpAddress);
073    container.setResource(resource);
074    container.setPriority(priority);
075    container.setContainerToken(containerToken);
076    return container;
077  }
078
079  /**
080   * Get the globally unique identifier for the container.
081   * @return globally unique identifier for the container
082   */
083  @Public
084  @Stable
085  public abstract ContainerId getId();
086  
087  @Private
088  @Unstable
089  public abstract void setId(ContainerId id);
090
091  /**
092   * Get the identifier of the node on which the container is allocated.
093   * @return identifier of the node on which the container is allocated
094   */
095  @Public
096  @Stable
097  public abstract NodeId getNodeId();
098  
099  @Private
100  @Unstable
101  public abstract void setNodeId(NodeId nodeId);
102  
103  /**
104   * Get the http uri of the node on which the container is allocated.
105   * @return http uri of the node on which the container is allocated
106   */
107  @Public
108  @Stable
109  public abstract String getNodeHttpAddress();
110  
111  @Private
112  @Unstable
113  public abstract void setNodeHttpAddress(String nodeHttpAddress);
114  
115  /**
116   * Get the <code>Resource</code> allocated to the container.
117   * @return <code>Resource</code> allocated to the container
118   */
119  @Public
120  @Stable
121  public abstract Resource getResource();
122  
123  @Private
124  @Unstable
125  public abstract void setResource(Resource resource);
126
127  /**
128   * Get the <code>Priority</code> at which the <code>Container</code> was
129   * allocated.
130   * @return <code>Priority</code> at which the <code>Container</code> was
131   *         allocated
132   */
133  @Public
134  @Stable
135  public abstract Priority getPriority();
136  
137  @Private
138  @Unstable
139  public abstract void setPriority(Priority priority);
140  
141  /**
142   * Get the <code>ContainerToken</code> for the container.
143   * <p><code>ContainerToken</code> is the security token used by the framework
144   * to verify authenticity of any <code>Container</code>.</p>
145   *
146   * <p>The <code>ResourceManager</code>, on container allocation provides a
147   * secure token which is verified by the <code>NodeManager</code> on
148   * container launch.</p>
149   *
150   * <p>Applications do not need to care about <code>ContainerToken</code>, they
151   * are transparently handled by the framework - the allocated
152   * <code>Container</code> includes the <code>ContainerToken</code>.</p>
153   *
154   * @see ApplicationMasterProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest)
155   * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest)
156   *
157   * @return <code>ContainerToken</code> for the container
158   */
159  @Public
160  @Stable
161  public abstract Token getContainerToken();
162  
163  @Private
164  @Unstable
165  public abstract void setContainerToken(Token containerToken);
166}