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    
019    package org.apache.hadoop.yarn.api.records;
020    
021    import org.apache.hadoop.classification.InterfaceAudience.Private;
022    import org.apache.hadoop.classification.InterfaceAudience.Public;
023    import org.apache.hadoop.classification.InterfaceStability.Stable;
024    import org.apache.hadoop.classification.InterfaceStability.Unstable;
025    import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
026    import org.apache.hadoop.yarn.api.ContainerManagementProtocol;
027    import 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
065    public 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    }