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.AMRMProtocol;
026import org.apache.hadoop.yarn.api.ContainerManager;
027
028/**
029 * <p><code>Container</code> represents an allocated resource in the cluster.
030 * </p>
031 * 
032 * <p>The <code>ResourceManager</code> is the sole authority to allocate any
033 * <code>Container</code> to applications. The allocated <code>Container</code>
034 * is always on a single node and has a unique {@link ContainerId}. It has
035 * a specific amount of {@link Resource} allocated.</p>
036 * 
037 * <p>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>{@link ContainerState} of the container.</li>
047 *     <li>
048 *       {@link ContainerToken} of the container, used to securely verify 
049 *       authenticity of the allocation. 
050 *     </li>
051 *     <li>{@link ContainerStatus} of the container.</li>
052 *   </ul>
053 * </p>
054 * 
055 * <p>Typically, an <code>ApplicationMaster</code> receives the 
056 * <code>Container</code> from the <code>ResourceManager</code> during
057 * resource-negotiation and then talks to the <code>NodManager</code> to 
058 * start/stop containers.</p>
059 * 
060 * @see AMRMProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest)
061 * @see ContainerManager#startContainer(org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest)
062 * @see ContainerManager#stopContainer(org.apache.hadoop.yarn.api.protocolrecords.StopContainerRequest)
063 */
064@Public
065@Stable
066public interface Container extends Comparable<Container> {
067  /**
068   * Get the globally unique identifier for the container.
069   * @return globally unique identifier for the container
070   */
071  @Public
072  @Stable
073  ContainerId getId();
074  
075  @Private
076  @Unstable
077  void setId(ContainerId id);
078
079  /**
080   * Get the identifier of the node on which the container is allocated.
081   * @return identifier of the node on which the container is allocated
082   */
083  @Public
084  @Stable
085  NodeId getNodeId();
086  
087  @Private
088  @Unstable
089  void setNodeId(NodeId nodeId);
090  
091  /**
092   * Get the http uri of the node on which the container is allocated.
093   * @return http uri of the node on which the container is allocated
094   */
095  @Public
096  @Stable
097  String getNodeHttpAddress();
098  
099  @Private
100  @Unstable
101  void setNodeHttpAddress(String nodeHttpAddress);
102  
103  /**
104   * Get the <code>Resource</code> allocated to the container.
105   * @return <code>Resource</code> allocated to the container
106   */
107  @Public
108  @Stable
109  Resource getResource();
110  
111  @Private
112  @Unstable
113  void setResource(Resource resource);
114
115  /**
116   * Get the <code>Priority</code> at which the <code>Container</code> was
117   * allocated.
118   * @return <code>Priority</code> at which the <code>Container</code> was
119   *         allocated
120   */
121  Priority getPriority();
122  
123  @Private
124  @Unstable
125  void setPriority(Priority priority);
126  
127  /**
128   * Get the current <code>ContainerState</code> of the container.
129   * @return current <code>ContainerState</code> of the container
130   */
131  @Public
132  @Stable
133  ContainerState getState();
134  
135  @Private
136  @Unstable
137  void setState(ContainerState state);
138  
139  /**
140   * Get the <code>ContainerToken</code> for the container.
141   * @return <code>ContainerToken</code> for the container
142   */
143  @Public
144  @Stable
145  ContainerToken getContainerToken();
146  
147  @Private
148  @Unstable
149  void setContainerToken(ContainerToken containerToken);
150  
151  /**
152   * Get the <code>ContainerStatus</code> of the container.
153   * @return <code>ContainerStatus</code> of the container
154   */
155  @Public
156  @Stable
157  ContainerStatus getContainerStatus();
158  
159  @Private
160  @Unstable
161  void setContainerStatus(ContainerStatus containerStatus);
162}