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