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.Evolving;
024import org.apache.hadoop.classification.InterfaceStability.Stable;
025import org.apache.hadoop.classification.InterfaceStability.Unstable;
026import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
027import org.apache.hadoop.yarn.api.ContainerManagementProtocol;
028import org.apache.hadoop.yarn.util.Records;
029
030/**
031 * {@code Container} represents an allocated resource in the cluster.
032 * <p>
033 * The {@code ResourceManager} is the sole authority to allocate any
034 * {@code Container} to applications. The allocated {@code Container}
035 * is always on a single node and has a unique {@link ContainerId}. It has
036 * a specific amount of {@link Resource} allocated.
037 * <p>
038 * It includes details such as:
039 * <ul>
040 *   <li>{@link ContainerId} for the container, which is globally unique.</li>
041 *   <li>
042 *     {@link NodeId} of the node on which it is allocated.
043 *   </li>
044 *   <li>HTTP uri of the node.</li>
045 *   <li>{@link Resource} allocated to the container.</li>
046 *   <li>{@link Priority} at which the container was allocated.</li>
047 *   <li>
048 *     Container {@link Token} of the container, used to securely verify
049 *     authenticity of the allocation.
050 *   </li>
051 * </ul>
052 * 
053 * Typically, an {@code ApplicationMaster} receives the {@code Container}
054 * from the {@code ResourceManager} during resource-negotiation and then
055 * talks to the {@code NodeManager} to start/stop containers.
056 * 
057 * @see ApplicationMasterProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest)
058 * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest)
059 * @see ContainerManagementProtocol#stopContainers(org.apache.hadoop.yarn.api.protocolrecords.StopContainersRequest)
060 */
061@Public
062@Stable
063public abstract class Container implements Comparable<Container> {
064
065  @Private
066  @Unstable
067  public static Container newInstance(ContainerId containerId, NodeId nodeId,
068      String nodeHttpAddress, Resource resource, Priority priority,
069      Token containerToken) {
070    return newInstance(containerId, nodeId, nodeHttpAddress, resource, priority,
071        containerToken, ExecutionType.GUARANTEED);
072  }
073
074  @Private
075  @Unstable
076  public static Container newInstance(ContainerId containerId, NodeId nodeId,
077      String nodeHttpAddress, Resource resource, Priority priority,
078      Token containerToken, ExecutionType executionType) {
079    Container container = Records.newRecord(Container.class);
080    container.setId(containerId);
081    container.setNodeId(nodeId);
082    container.setNodeHttpAddress(nodeHttpAddress);
083    container.setResource(resource);
084    container.setPriority(priority);
085    container.setContainerToken(containerToken);
086    container.setExecutionType(executionType);
087    return container;
088  }
089
090  /**
091   * Get the globally unique identifier for the container.
092   * @return globally unique identifier for the container
093   */
094  @Public
095  @Stable
096  public abstract ContainerId getId();
097  
098  @Private
099  @Unstable
100  public abstract void setId(ContainerId id);
101
102  /**
103   * Get the identifier of the node on which the container is allocated.
104   * @return identifier of the node on which the container is allocated
105   */
106  @Public
107  @Stable
108  public abstract NodeId getNodeId();
109  
110  @Private
111  @Unstable
112  public abstract void setNodeId(NodeId nodeId);
113  
114  /**
115   * Get the http uri of the node on which the container is allocated.
116   * @return http uri of the node on which the container is allocated
117   */
118  @Public
119  @Stable
120  public abstract String getNodeHttpAddress();
121  
122  @Private
123  @Unstable
124  public abstract void setNodeHttpAddress(String nodeHttpAddress);
125  
126  /**
127   * Get the <code>Resource</code> allocated to the container.
128   * @return <code>Resource</code> allocated to the container
129   */
130  @Public
131  @Stable
132  public abstract Resource getResource();
133  
134  @Private
135  @Unstable
136  public abstract void setResource(Resource resource);
137
138  /**
139   * Get the <code>Priority</code> at which the <code>Container</code> was
140   * allocated.
141   * @return <code>Priority</code> at which the <code>Container</code> was
142   *         allocated
143   */
144  @Public
145  @Stable
146  public abstract Priority getPriority();
147  
148  @Private
149  @Unstable
150  public abstract void setPriority(Priority priority);
151  
152  /**
153   * Get the <code>ContainerToken</code> for the container.
154   * <p><code>ContainerToken</code> is the security token used by the framework
155   * to verify authenticity of any <code>Container</code>.</p>
156   *
157   * <p>The <code>ResourceManager</code>, on container allocation provides a
158   * secure token which is verified by the <code>NodeManager</code> on
159   * container launch.</p>
160   *
161   * <p>Applications do not need to care about <code>ContainerToken</code>, they
162   * are transparently handled by the framework - the allocated
163   * <code>Container</code> includes the <code>ContainerToken</code>.</p>
164   *
165   * @see ApplicationMasterProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest)
166   * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest)
167   *
168   * @return <code>ContainerToken</code> for the container
169   */
170  @Public
171  @Stable
172  public abstract Token getContainerToken();
173  
174  @Private
175  @Unstable
176  public abstract void setContainerToken(Token containerToken);
177
178  /**
179   * Get the <code>ExecutionType</code> for the container.
180   * @return <code>ExecutionType</code> for the container.
181   */
182  @Private
183  @Unstable
184  public abstract ExecutionType getExecutionType();
185
186  /**
187   * Set the <code>ExecutionType</code> for the container.
188   * @param executionType ExecutionType
189   */
190  @Private
191  @Unstable
192  public abstract void setExecutionType(ExecutionType executionType);
193
194  /**
195   * Get the optional <em>ID</em> corresponding to the original {@code
196   * ResourceRequest{@link #getAllocationRequestId()}}s which is satisfied by
197   * this allocated {@code Container}.
198   * <p>
199   * The scheduler may return multiple {@code AllocateResponse}s corresponding
200   * to the same ID as and when scheduler allocates {@code Container}s.
201   * <b>Applications</b> can continue to completely ignore the returned ID in
202   * the response and use the allocation for any of their outstanding requests.
203   * <p>
204   *
205   * @return the <em>ID</em> corresponding to the original  allocation request
206   * which is satisfied by this allocation.
207   */
208  @Public
209  @Evolving
210  public long getAllocationRequestId() {
211    throw new UnsupportedOperationException();
212  }
213
214  /**
215   * Set the optional <em>ID</em> corresponding to the original {@code
216   * ResourceRequest{@link #setAllocationRequestId(long)}
217   * etAllocationRequestId()}}s which is satisfied by this allocated {@code
218   * Container}.
219   * <p>
220   * The scheduler may return multiple {@code AllocateResponse}s corresponding
221   * to the same ID as and when scheduler allocates {@code Container}s.
222   * <b>Applications</b> can continue to completely ignore the returned ID in
223   * the response and use the allocation for any of their outstanding requests.
224   * If the ID is not set, scheduler will continue to work as previously and all
225   * allocated {@code Container}(s) will have the default ID, -1.
226   * <p>
227   *
228   * @param allocationRequestID the <em>ID</em> corresponding to the original
229   *                            allocation request which is satisfied by this
230   *                            allocation.
231   */
232  @Private
233  @Evolving
234  public void setAllocationRequestId(long allocationRequestID) {
235    throw new UnsupportedOperationException();
236  }
237}