org.springframework.yarn.config.annotation.builders.YarnEnvironmentConfigurer Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of spring-yarn-core Show documentation
Spring Yarn Core
The newest version!
/*
 * Copyright 2013 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.springframework.yarn.config.annotation.builders;

import java.io.IOException;

import org.springframework.data.hadoop.config.common.annotation.configurers.PropertiesConfigurer;
import org.springframework.yarn.config.annotation.SpringYarnConfigurerAdapter;
import org.springframework.yarn.config.annotation.configurers.EnvironmentClasspathConfigurer;
import org.springframework.yarn.config.annotation.configurers.DefaultEnvironmentClasspathConfigurer;

/**
 * Interface for {@link YarnEnvironmentBuilder} used from
 * a {@link SpringYarnConfigurerAdapter}.
 * 
 * Typically configuration is used as shown below.
 * 

 * 
 * @Configuration
 * @EnableYarn
 * static class Config extends SpringYarnConfigurerAdapter {
 *
 *   @Override
 *   public void configure(YarnEnvironmentBuilder environment) throws Exception {
 *     environment
 *       .withClasspath()
 *         .entry("cpEntry1")
 *         .entry("cpEntry2")
 *         .useDefaultYarnClasspath(true);
 *   }
 *
 * }
 * 
 *
 * @author Janne Valkealahti
 *
 */
public interface YarnEnvironmentConfigurer {

	/**
	 * Specify a classpath environment variable.
	 * 
	 * Applies a new {@link DefaultEnvironmentClasspathConfigurer} into current
	 * builder. Equivalents between JavaConfig and XML are shown below.
	 *
	 * 
JavaConfig:
	 * 
	 * public void configure(YarnEnvironmentBuilder environment) throws Exception {
	 *   environment
	 *     .withClasspath()
	 *       .entry("cpEntry1")
	 *       .entry("cpEntry2")
	 *       .useDefaultYarnClasspath(true);
	 * }
	 * 
	 * 
XML:
	 * 	 * <yarn:environment>
	 *   <yarn:classpath use-yarn-app-classpath="true" delimiter=":">
	 *     cpEntry1
	 *     cpEntry2
	 *   </yarn:classpath>
	 * </yarn:environment>
	 * 
	 *
	 * @return {@link EnvironmentClasspathConfigurer} for classpath
	 * @throws Exception if error occurred
	 */
	EnvironmentClasspathConfigurer withClasspath() throws Exception;

	/**
	 * Specify a classpath environment variable using an identifier.
	 *
	 * @param id the identifier
	 * @return {@link EnvironmentClasspathConfigurer} for classpath
	 * @throws Exception if error occurred
	 * @see #withClasspath()
	 */
	EnvironmentClasspathConfigurer withClasspath(String id) throws Exception;

	/**
	 * Specify an environment variable.
	 *
	 * 
JavaConfig:
	 * 	 * public void configure(YarnEnvironmentConfigure environment) throws Exception {
	 *   environment
	 *     .entry("myKey1","myValue1")
	 *     .entry("myKey2","myValue2");
	 * }
	 * 
	 *
	 * 
XML:
	 * 	 * <yarn:environment>
	 *   myKey1=myValue1
	 *   myKey2=myValue2
	 * </yarn:environment>
	 * 
	 *
	 * @param key The environment key
	 * @param value The environment value
	 * @return {@link YarnEnvironmentConfigurer} for chaining
	 */
	YarnEnvironmentConfigurer entry(String key, String value);

	/**
	 * Specify an environment variable using an identifier.
	 *
	 * @param id the identifier
	 * @param key The environment key
	 * @param value The environment value
	 * @return {@link YarnEnvironmentConfigurer} for chaining
	 * @see #entry(String, String)
	 */
	YarnEnvironmentConfigurer entry(String id, String key, String value);

	/**
	 * Specify properties locations.
	 *
	 * 
JavaConfig:
	 * 	 * public void configure(YarnEnvironmentConfigure environment) throws Exception {
	 *   environment
	 *     .entry("myKey1","myValue1")
	 *     .entry("myKey2","myValue2")
	 *     .propertiesLocation("cfg-1.properties", "cfg-2.properties");
	 * }
	 * 
	 *
	 * 
XML:
	 * 	 * <yarn:environment properties-location="cfg-1.properties, cfg-2.properties">
	 *   myKey1=myValue1
	 *   myKey2=myValue2
	 * </yarn:environment>
	 * 
	 *
	 * @param locations The properties file locations
	 * @return {@link YarnEnvironmentConfigurer} for chaining
	 * @throws IOException if error occurred
	 */
	YarnEnvironmentConfigurer propertiesLocation(String... locations) throws IOException;

	/**
	 * Specify properties locations with an identifier.
	 *
	 * @param id the identifier
	 * @param locations the properties file locations
	 * @return {@link YarnEnvironmentConfigurer} for chaining
	 * @throws IOException if error occurred
	 * @see #propertiesLocation(String...)
	 */
	YarnEnvironmentConfigurer propertiesLocationId(String id, String[] locations) throws IOException;

	/**
	 * Specify if existing system environment variables should
	 * be included automatically.
	 *
	 * 
JavaConfig:
	 * 	 * public void configure(YarnEnvironmentConfigure environment) throws Exception {
	 *   environment
	 *     .includeLocalSystemEnv(false);
	 * }
	 * 
	 *
	 * 
XML:
	 * 	 * <yarn:environment include-local-system-env="false"/>
	 * 
	 *
	 * @param includeLocalSystemEnv if system env variables should be included
	 * @return {@link YarnEnvironmentConfigurer} for chaining
	 */
	YarnEnvironmentConfigurer includeLocalSystemEnv(boolean includeLocalSystemEnv);

	/**
	 * Specify if existing system environment variables should
	 * be included automatically with an identifier.
	 *
	 * @param id the identifier
	 * @param includeLocalSystemEnv if system env variables should be included
	 * @return {@link YarnEnvironmentConfigurer} for chaining
	 * @see #includeLocalSystemEnv(boolean)
	 */
	YarnEnvironmentConfigurer includeLocalSystemEnv(String id, boolean includeLocalSystemEnv);

	/**
	 * Specify properties with a {@link org.springframework.data.hadoop.config.common.annotation.configurers.PropertiesConfigurer}.
	 *
	 * 
JavaConfig:
	 * 	 * public void configure(YarnEnvironmentConfigure environment) throws Exception {
	 *   Properties props = new Properties();
	 *   environment
	 *     .withProperties()
	 *       .properties(props)
	 *       .property("myKey1", ",myValue1")
	 *       .and();
	 * }
	 * 
	 *
	 * 
XML:
	 * 	 * <util:properties id="props" location="props.properties"/>
	 *   <prop key="myKey1">myValue1</prop>
	 * </util:properties>
	 * <yarn:environment properties-ref="props"/>
	 * 
	 *
	 * @return {@link org.springframework.data.hadoop.config.common.annotation.configurers.PropertiesConfigurer} for chaining
	 * @throws Exception if error occurred
	 */
	PropertiesConfigurer withProperties() throws Exception;

	/**
	 * Specify properties with a {@link org.springframework.data.hadoop.config.common.annotation.configurers.PropertiesConfigurer}
	 * with an identifier.
	 *
	 * @param id the identifier
	 * @return {@link org.springframework.data.hadoop.config.common.annotation.configurers.PropertiesConfigurer} for chaining
	 * @throws Exception if error occurred
	 * @see #withProperties()
	 */
	PropertiesConfigurer withProperties(String id) throws Exception;

}