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.AMRMProtocol;
026    import 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
066    public 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    }