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 java.nio.ByteBuffer; 022import java.util.List; 023import java.util.Map; 024 025import org.apache.hadoop.classification.InterfaceAudience.Public; 026import org.apache.hadoop.classification.InterfaceStability.Stable; 027import org.apache.hadoop.yarn.api.ContainerManagementProtocol; 028import org.apache.hadoop.yarn.server.api.ApplicationInitializationContext; 029import org.apache.hadoop.yarn.server.api.AuxiliaryService; 030import org.apache.hadoop.yarn.util.Records; 031 032/** 033 * {@code ContainerLaunchContext} represents all of the information 034 * needed by the {@code NodeManager} to launch a container. 035 * <p> 036 * It includes details such as: 037 * <ul> 038 * <li>{@link ContainerId} of the container.</li> 039 * <li>{@link Resource} allocated to the container.</li> 040 * <li>User to whom the container is allocated.</li> 041 * <li>Security tokens (if security is enabled).</li> 042 * <li> 043 * {@link LocalResource} necessary for running the container such 044 * as binaries, jar, shared-objects, side-files etc. 045 * </li> 046 * <li>Optional, application-specific binary service data.</li> 047 * <li>Environment variables for the launched process.</li> 048 * <li>Command to launch the container.</li> 049 * </ul> 050 * 051 * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest) 052 */ 053@Public 054@Stable 055public abstract class ContainerLaunchContext { 056 057 @Public 058 @Stable 059 public static ContainerLaunchContext newInstance( 060 Map<String, LocalResource> localResources, 061 Map<String, String> environment, List<String> commands, 062 Map<String, ByteBuffer> serviceData, ByteBuffer tokens, 063 Map<ApplicationAccessType, String> acls) { 064 ContainerLaunchContext container = 065 Records.newRecord(ContainerLaunchContext.class); 066 container.setLocalResources(localResources); 067 container.setEnvironment(environment); 068 container.setCommands(commands); 069 container.setServiceData(serviceData); 070 container.setTokens(tokens); 071 container.setApplicationACLs(acls); 072 return container; 073 } 074 075 /** 076 * Get all the tokens needed by this container. It may include file-system 077 * tokens, ApplicationMaster related tokens if this container is an 078 * ApplicationMaster or framework level tokens needed by this container to 079 * communicate to various services in a secure manner. 080 * 081 * @return tokens needed by this container. 082 */ 083 @Public 084 @Stable 085 public abstract ByteBuffer getTokens(); 086 087 /** 088 * Set security tokens needed by this container. 089 * @param tokens security tokens 090 */ 091 @Public 092 @Stable 093 public abstract void setTokens(ByteBuffer tokens); 094 095 /** 096 * Get <code>LocalResource</code> required by the container. 097 * @return all <code>LocalResource</code> required by the container 098 */ 099 @Public 100 @Stable 101 public abstract Map<String, LocalResource> getLocalResources(); 102 103 /** 104 * Set <code>LocalResource</code> required by the container. All pre-existing 105 * Map entries are cleared before adding the new Map 106 * @param localResources <code>LocalResource</code> required by the container 107 */ 108 @Public 109 @Stable 110 public abstract void setLocalResources(Map<String, LocalResource> localResources); 111 112 /** 113 * <p> 114 * Get application-specific binary <em>service data</em>. This is a map keyed 115 * by the name of each {@link AuxiliaryService} that is configured on a 116 * NodeManager and value correspond to the application specific data targeted 117 * for the keyed {@link AuxiliaryService}. 118 * </p> 119 * 120 * <p> 121 * This will be used to initialize this application on the specific 122 * {@link AuxiliaryService} running on the NodeManager by calling 123 * {@link AuxiliaryService#initializeApplication(ApplicationInitializationContext)} 124 * </p> 125 * 126 * @return application-specific binary <em>service data</em> 127 */ 128 @Public 129 @Stable 130 public abstract Map<String, ByteBuffer> getServiceData(); 131 132 /** 133 * <p> 134 * Set application-specific binary <em>service data</em>. This is a map keyed 135 * by the name of each {@link AuxiliaryService} that is configured on a 136 * NodeManager and value correspond to the application specific data targeted 137 * for the keyed {@link AuxiliaryService}. All pre-existing Map entries are 138 * preserved. 139 * </p> 140 * 141 * @param serviceData 142 * application-specific binary <em>service data</em> 143 */ 144 @Public 145 @Stable 146 public abstract void setServiceData(Map<String, ByteBuffer> serviceData); 147 148 /** 149 * Get <em>environment variables</em> for the container. 150 * @return <em>environment variables</em> for the container 151 */ 152 @Public 153 @Stable 154 public abstract Map<String, String> getEnvironment(); 155 156 /** 157 * Add <em>environment variables</em> for the container. All pre-existing Map 158 * entries are cleared before adding the new Map 159 * @param environment <em>environment variables</em> for the container 160 */ 161 @Public 162 @Stable 163 public abstract void setEnvironment(Map<String, String> environment); 164 165 /** 166 * Get the list of <em>commands</em> for launching the container. 167 * @return the list of <em>commands</em> for launching the container 168 */ 169 @Public 170 @Stable 171 public abstract List<String> getCommands(); 172 173 /** 174 * Add the list of <em>commands</em> for launching the container. All 175 * pre-existing List entries are cleared before adding the new List 176 * @param commands the list of <em>commands</em> for launching the container 177 */ 178 @Public 179 @Stable 180 public abstract void setCommands(List<String> commands); 181 182 /** 183 * Get the <code>ApplicationACL</code>s for the application. 184 * @return all the <code>ApplicationACL</code>s 185 */ 186 @Public 187 @Stable 188 public abstract Map<ApplicationAccessType, String> getApplicationACLs(); 189 190 /** 191 * Set the <code>ApplicationACL</code>s for the application. All pre-existing 192 * Map entries are cleared before adding the new Map 193 * @param acls <code>ApplicationACL</code>s for the application 194 */ 195 @Public 196 @Stable 197 public abstract void setApplicationACLs(Map<ApplicationAccessType, String> acls); 198}