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.protocolrecords;
020    
021    import org.apache.hadoop.classification.InterfaceAudience.Public;
022    import org.apache.hadoop.classification.InterfaceStability.Stable;
023    import org.apache.hadoop.yarn.api.ContainerManagementProtocol;
024    import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
025    import org.apache.hadoop.yarn.api.records.NMToken;
026    import org.apache.hadoop.yarn.api.records.Token;
027    import org.apache.hadoop.yarn.util.Records;
028    
029    /**
030     * <p>The request sent by the <code>ApplicationMaster</code> to the
031     * <code>NodeManager</code> to <em>start</em> a container.</p>
032     * 
033     * <p>The <code>ApplicationMaster</code> has to provide details such as
034     * allocated resource capability, security tokens (if enabled), command
035     * to be executed to start the container, environment for the process, 
036     * necessary binaries/jar/shared-objects etc. via the 
037     * {@link ContainerLaunchContext}.</p>
038     *
039     * @see ContainerManagementProtocol#startContainers(StartContainersRequest)
040     */
041    @Public
042    @Stable
043    public abstract class StartContainerRequest {
044      @Public
045      @Stable
046      public static StartContainerRequest newInstance(
047          ContainerLaunchContext context, Token container) {
048        StartContainerRequest request =
049            Records.newRecord(StartContainerRequest.class);
050        request.setContainerLaunchContext(context);
051        request.setContainerToken(container);
052        return request;
053      }
054    
055      /**
056       * Get the <code>ContainerLaunchContext</code> for the container to be started
057       * by the <code>NodeManager</code>.
058       * 
059       * @return <code>ContainerLaunchContext</code> for the container to be started
060       *         by the <code>NodeManager</code>
061       */
062      @Public
063      @Stable
064      public abstract ContainerLaunchContext getContainerLaunchContext();
065      
066      /**
067       * Set the <code>ContainerLaunchContext</code> for the container to be started
068       * by the <code>NodeManager</code>
069       * @param context <code>ContainerLaunchContext</code> for the container to be 
070       *                started by the <code>NodeManager</code>
071       */
072      @Public
073      @Stable
074      public abstract void setContainerLaunchContext(ContainerLaunchContext context);
075    
076      /**
077       * <p>Get the container token to be used for authorization during starting
078       * container.</p>
079       * <p>Note: {@link NMToken} will be used for authenticating communication with </code>
080       * NodeManager</code>.</p>
081       * @return the container token to be used for authorization during starting
082       * container.
083       * @see NMToken
084       * @see ContainerManagementProtocol#startContainers(StartContainersRequest)
085       */
086      @Public
087      @Stable
088      public abstract Token getContainerToken();
089    
090      @Public
091      @Stable
092      public abstract void setContainerToken(Token container);
093    }