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 * <p><code>Container</code> represents an allocated resource in the cluster.
031 * </p>
032 * 
033 * <p>The <code>ResourceManager</code> is the sole authority to allocate any
034 * <code>Container</code> to applications. The allocated <code>Container</code>
035 * is always on a single node and has a unique {@link ContainerId}. It has
036 * a specific amount of {@link Resource} allocated.</p>
037 * 
038 * <p>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 * </p>
053 * 
054 * <p>Typically, an <code>ApplicationMaster</code> receives the 
055 * <code>Container</code> from the <code>ResourceManager</code> during
056 * resource-negotiation and then talks to the <code>NodeManager</code> to 
057 * start/stop containers.</p>
058 * 
059 * @see ApplicationMasterProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest)
060 * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest)
061 * @see ContainerManagementProtocol#stopContainers(org.apache.hadoop.yarn.api.protocolrecords.StopContainersRequest)
062 */
063@Public
064@Stable
065public abstract class Container implements Comparable<Container> {
066
067  @Private
068  @Unstable
069  public static Container newInstance(ContainerId containerId, NodeId nodeId,
070      String nodeHttpAddress, Resource resource, Priority priority,
071      Token containerToken) {
072    Container container = Records.newRecord(Container.class);
073    container.setId(containerId);
074    container.setNodeId(nodeId);
075    container.setNodeHttpAddress(nodeHttpAddress);
076    container.setResource(resource);
077    container.setPriority(priority);
078    container.setContainerToken(containerToken);
079    return container;
080  }
081
082  /**
083   * Get the globally unique identifier for the container.
084   * @return globally unique identifier for the container
085   */
086  @Public
087  @Stable
088  public abstract ContainerId getId();
089  
090  @Private
091  @Unstable
092  public abstract void setId(ContainerId id);
093
094  /**
095   * Get the identifier of the node on which the container is allocated.
096   * @return identifier of the node on which the container is allocated
097   */
098  @Public
099  @Stable
100  public abstract NodeId getNodeId();
101  
102  @Private
103  @Unstable
104  public abstract void setNodeId(NodeId nodeId);
105  
106  /**
107   * Get the http uri of the node on which the container is allocated.
108   * @return http uri of the node on which the container is allocated
109   */
110  @Public
111  @Stable
112  public abstract String getNodeHttpAddress();
113  
114  @Private
115  @Unstable
116  public abstract void setNodeHttpAddress(String nodeHttpAddress);
117  
118  /**
119   * Get the <code>Resource</code> allocated to the container.
120   * @return <code>Resource</code> allocated to the container
121   */
122  @Public
123  @Stable
124  public abstract Resource getResource();
125  
126  @Private
127  @Unstable
128  public abstract void setResource(Resource resource);
129
130  /**
131   * Get the <code>Priority</code> at which the <code>Container</code> was
132   * allocated.
133   * @return <code>Priority</code> at which the <code>Container</code> was
134   *         allocated
135   */
136  @Public
137  @Stable
138  public abstract Priority getPriority();
139  
140  @Private
141  @Unstable
142  public abstract void setPriority(Priority priority);
143  
144  /**
145   * Get the <code>ContainerToken</code> for the container.
146   * <p><code>ContainerToken</code> is the security token used by the framework
147   * to verify authenticity of any <code>Container</code>.</p>
148   *
149   * <p>The <code>ResourceManager</code>, on container allocation provides a
150   * secure token which is verified by the <code>NodeManager</code> on
151   * container launch.</p>
152   *
153   * <p>Applications do not need to care about <code>ContainerToken</code>, they
154   * are transparently handled by the framework - the allocated
155   * <code>Container</code> includes the <code>ContainerToken</code>.</p>
156   *
157   * @see ApplicationMasterProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest)
158   * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest)
159   *
160   * @return <code>ContainerToken</code> for the container
161   */
162  @Public
163  @Stable
164  public abstract Token getContainerToken();
165  
166  @Private
167  @Unstable
168  public abstract void setContainerToken(Token containerToken);
169}