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 org.apache.hadoop.classification.InterfaceAudience.Public;
022import org.apache.hadoop.classification.InterfaceStability.Stable;
023import org.apache.hadoop.classification.InterfaceStability.Unstable;
024import org.apache.hadoop.yarn.api.ContainerManagementProtocol;
025import org.apache.hadoop.yarn.util.Records;
026
027/**
028 * <p><code>LocalResource</code> represents a local resource required to
029 * run a container.</p>
030 * 
031 * <p>The <code>NodeManager</code> is responsible for localizing the resource 
032 * prior to launching the container.</p>
033 * 
034 * <p>Applications can specify {@link LocalResourceType} and 
035 * {@link LocalResourceVisibility}.</p>
036 * 
037 * @see LocalResourceType
038 * @see LocalResourceVisibility
039 * @see ContainerLaunchContext
040 * @see ApplicationSubmissionContext
041 * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest)
042 */
043@Public
044@Stable
045public abstract class LocalResource {
046
047  @Public
048  @Stable
049  public static LocalResource newInstance(URL url, LocalResourceType type,
050      LocalResourceVisibility visibility, long size, long timestamp,
051      String pattern) {
052    return newInstance(url, type, visibility, size, timestamp, pattern, false);
053  }
054
055  @Public
056  @Unstable
057  public static LocalResource newInstance(URL url, LocalResourceType type,
058      LocalResourceVisibility visibility, long size, long timestamp,
059      String pattern, boolean shouldBeUploadedToSharedCache) {
060    LocalResource resource = Records.newRecord(LocalResource.class);
061    resource.setResource(url);
062    resource.setType(type);
063    resource.setVisibility(visibility);
064    resource.setSize(size);
065    resource.setTimestamp(timestamp);
066    resource.setPattern(pattern);
067    resource.setShouldBeUploadedToSharedCache(shouldBeUploadedToSharedCache);
068    return resource;
069  }
070
071  @Public
072  @Stable
073  public static LocalResource newInstance(URL url, LocalResourceType type,
074      LocalResourceVisibility visibility, long size, long timestamp) {
075    return newInstance(url, type, visibility, size, timestamp, null);
076  }
077
078  @Public
079  @Unstable
080  public static LocalResource newInstance(URL url, LocalResourceType type,
081      LocalResourceVisibility visibility, long size, long timestamp,
082      boolean shouldBeUploadedToSharedCache) {
083    return newInstance(url, type, visibility, size, timestamp, null,
084        shouldBeUploadedToSharedCache);
085  }
086
087  /**
088   * Get the <em>location</em> of the resource to be localized.
089   * @return <em>location</em> of the resource to be localized
090   */
091  @Public
092  @Stable
093  public abstract URL getResource();
094  
095  /**
096   * Set <em>location</em> of the resource to be localized.
097   * @param resource <em>location</em> of the resource to be localized
098   */
099  @Public
100  @Stable
101  public abstract void setResource(URL resource);
102  
103  /**
104   * Get the <em>size</em> of the resource to be localized.
105   * @return <em>size</em> of the resource to be localized
106   */
107  @Public
108  @Stable
109  public abstract long getSize();
110  
111  /**
112   * Set the <em>size</em> of the resource to be localized.
113   * @param size <em>size</em> of the resource to be localized
114   */
115  @Public
116  @Stable
117  public abstract void setSize(long size);
118  
119  /**
120   * Get the original <em>timestamp</em> of the resource to be localized, used
121   * for verification.
122   * @return <em>timestamp</em> of the resource to be localized
123   */
124  @Public
125  @Stable
126  public abstract long getTimestamp();
127  
128  /**
129   * Set the <em>timestamp</em> of the resource to be localized, used
130   * for verification.
131   * @param timestamp <em>timestamp</em> of the resource to be localized
132   */
133  @Public
134  @Stable
135  public abstract void setTimestamp(long timestamp);
136  
137  /**
138   * Get the <code>LocalResourceType</code> of the resource to be localized.
139   * @return <code>LocalResourceType</code> of the resource to be localized
140   */
141  @Public
142  @Stable
143  public abstract LocalResourceType getType();
144  
145  /**
146   * Set the <code>LocalResourceType</code> of the resource to be localized.
147   * @param type <code>LocalResourceType</code> of the resource to be localized
148   */
149  @Public
150  @Stable
151  public abstract void setType(LocalResourceType type);
152  
153  /**
154   * Get the <code>LocalResourceVisibility</code> of the resource to be 
155   * localized.
156   * @return <code>LocalResourceVisibility</code> of the resource to be 
157   *         localized
158   */
159  @Public
160  @Stable
161  public abstract LocalResourceVisibility getVisibility();
162  
163  /**
164   * Set the <code>LocalResourceVisibility</code> of the resource to be 
165   * localized.
166   * @param visibility <code>LocalResourceVisibility</code> of the resource to be 
167   *                   localized
168   */
169  @Public
170  @Stable
171  public abstract void setVisibility(LocalResourceVisibility visibility);
172  
173  /**
174   * Get the <em>pattern</em> that should be used to extract entries from the
175   * archive (only used when type is <code>PATTERN</code>).
176   * @return <em>pattern</em> that should be used to extract entries from the 
177   * archive. 
178   */
179  @Public
180  @Stable
181  public abstract String getPattern();
182  
183  /**
184   * Set the <em>pattern</em> that should be used to extract entries from the
185   * archive (only used when type is <code>PATTERN</code>).
186   * @param pattern <em>pattern</em> that should be used to extract entries 
187   * from the archive.
188   */
189  @Public
190  @Stable
191  public abstract void setPattern(String pattern);
192
193  /**
194   * NM uses it to decide whether if it is necessary to upload the resource to
195   * the shared cache
196   * @return true if it is necessary to upload the resource
197   *                 to the shared cache,
198   *         false otherwise
199   */
200  @Public
201  @Unstable
202  public abstract boolean getShouldBeUploadedToSharedCache();
203
204  /**
205   * Inform NM whether upload to SCM is needed.
206   *
207   * @param shouldBeUploadedToSharedCache <em>shouldBeUploadedToSharedCache</em>
208   *          of this request
209   */
210  @Public
211  @Unstable
212  public abstract void setShouldBeUploadedToSharedCache(
213      boolean shouldBeUploadedToSharedCache);
214}