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,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.reef.client;
020
021import org.apache.reef.annotations.Provided;
022import org.apache.reef.annotations.audience.ClientSide;
023import org.apache.reef.annotations.audience.Public;
024import org.apache.reef.driver.context.ActiveContext;
025import org.apache.reef.driver.context.ClosedContext;
026import org.apache.reef.driver.context.ContextMessage;
027import org.apache.reef.driver.context.FailedContext;
028import org.apache.reef.driver.evaluator.AllocatedEvaluator;
029import org.apache.reef.driver.evaluator.CompletedEvaluator;
030import org.apache.reef.driver.evaluator.FailedEvaluator;
031import org.apache.reef.driver.parameters.*;
032import org.apache.reef.driver.restart.DriverRestarted;
033import org.apache.reef.driver.task.*;
034import org.apache.reef.tang.formats.*;
035import org.apache.reef.wake.EventHandler;
036import org.apache.reef.wake.time.Clock;
037import org.apache.reef.wake.time.event.StartTime;
038import org.apache.reef.wake.time.event.StopTime;
039
040/**
041 * Use this ConfigurationModule to configure Services to be run in the Driver.
042 * <p>
043 * A service is a set of event handlers that are informed of events in addition to * the event handlers defined in
044 * DriverConfiguration. However, most services will treat the events as read-only. Doing differently should be
045 * documented clearly in the Service documentation.
046 */
047@ClientSide
048@Public
049@Provided
050public final class DriverServiceConfiguration extends ConfigurationModuleBuilder {
051
052
053  /**
054   * Files to be made available on the Driver and all Evaluators.
055   */
056  public static final OptionalParameter<String> GLOBAL_FILES = new OptionalParameter<>();
057
058  /**
059   * Libraries to be made available on the Driver and all Evaluators.
060   */
061  public static final OptionalParameter<String> GLOBAL_LIBRARIES = new OptionalParameter<>();
062
063  /**
064   * Files to be made available on the Driver only.
065   */
066  public static final OptionalParameter<String> LOCAL_FILES = new OptionalParameter<>();
067
068  /**
069   * Libraries to be made available on the Driver only.
070   */
071  public static final OptionalParameter<String> LOCAL_LIBRARIES = new OptionalParameter<>();
072
073  /**
074   * The event handler invoked right after the driver boots up.
075   */
076  public static final RequiredImpl<EventHandler<StartTime>> ON_DRIVER_STARTED = new RequiredImpl<>();
077
078  /**
079   * The event handler invoked right after the driver restarts.
080   */
081  public static final OptionalImpl<EventHandler<DriverRestarted>> ON_DRIVER_RESTARTED = new OptionalImpl<>();
082
083  /**
084   * The event handler invoked right before the driver shuts down. Defaults to ignore.
085   */
086  public static final OptionalImpl<EventHandler<StopTime>> ON_DRIVER_STOP = new OptionalImpl<>();
087
088  // ***** EVALUATOR HANDLER BINDINGS:
089
090  /**
091   * Event handler for allocated evaluators. Defaults to returning the evaluator if not bound.
092   */
093  public static final OptionalImpl<EventHandler<AllocatedEvaluator>> ON_EVALUATOR_ALLOCATED = new OptionalImpl<>();
094
095  /**
096   * Event handler for completed evaluators. Defaults to logging if not bound.
097   */
098  public static final OptionalImpl<EventHandler<CompletedEvaluator>> ON_EVALUATOR_COMPLETED = new OptionalImpl<>();
099
100  /**
101   * Event handler for failed evaluators. Defaults to job failure if not bound.
102   */
103  public static final OptionalImpl<EventHandler<FailedEvaluator>> ON_EVALUATOR_FAILED = new OptionalImpl<>();
104
105  // ***** TASK HANDLER BINDINGS:
106
107  /**
108   * Event handler for task messages. Defaults to logging if not bound.
109   */
110  public static final OptionalImpl<EventHandler<TaskMessage>> ON_TASK_MESSAGE = new OptionalImpl<>();
111
112  /**
113   * Event handler for completed tasks. Defaults to closing the context the task ran on if not bound.
114   */
115  public static final OptionalImpl<EventHandler<CompletedTask>> ON_TASK_COMPLETED = new OptionalImpl<>();
116
117  /**
118   * Event handler for failed tasks. Defaults to job failure if not bound.
119   */
120  public static final OptionalImpl<EventHandler<FailedTask>> ON_TASK_FAILED = new OptionalImpl<>();
121
122  /**
123   * Event handler for running tasks. Defaults to logging if not bound.
124   */
125  public static final OptionalImpl<EventHandler<RunningTask>> ON_TASK_RUNNING = new OptionalImpl<>();
126
127  /**
128   * Event handler for suspended tasks. Defaults to job failure if not bound. Rationale: many jobs don't support
129   * task suspension. Hence, this parameter should be optional. The only sane default is to crash the job, then.
130   */
131  public static final OptionalImpl<EventHandler<SuspendedTask>> ON_TASK_SUSPENDED = new OptionalImpl<>();
132
133
134  // ***** CONTEXT HANDLER BINDINGS:
135
136  /**
137   * Event handler for active context. Defaults to closing the context if not bound.
138   */
139  public static final OptionalImpl<EventHandler<ActiveContext>> ON_CONTEXT_ACTIVE = new OptionalImpl<>();
140
141  /**
142   * Event handler for closed context. Defaults to logging if not bound.
143   */
144  public static final OptionalImpl<EventHandler<ClosedContext>> ON_CONTEXT_CLOSED = new OptionalImpl<>();
145
146  /**
147   * Event handler for closed context. Defaults to job failure if not bound.
148   */
149  public static final OptionalImpl<EventHandler<FailedContext>> ON_CONTEXT_FAILED = new OptionalImpl<>();
150
151  /**
152   * Event handler for context messages. Defaults to logging if not bound.
153   */
154  public static final OptionalImpl<EventHandler<ContextMessage>> ON_CONTEXT_MESSAGE = new OptionalImpl<>();
155
156
157  /**
158   * ConfigurationModule to fill out to get a legal Driver Configuration.
159   */
160  public static final ConfigurationModule CONF = new DriverServiceConfiguration()
161      // Files use the very same named parameters as the DriverConfiguration
162      .bindSetEntry(JobGlobalFiles.class, GLOBAL_FILES)
163      .bindSetEntry(JobGlobalLibraries.class, GLOBAL_LIBRARIES)
164      .bindSetEntry(DriverLocalFiles.class, LOCAL_FILES)
165      .bindSetEntry(DriverLocalLibraries.class, LOCAL_LIBRARIES)
166
167          // Start and stop events are the same handlers for applications and services.
168      .bindSetEntry(Clock.StartHandler.class, ON_DRIVER_STARTED)
169      .bindSetEntry(Clock.StopHandler.class, ON_DRIVER_STOP)
170      .bindSetEntry(ServiceDriverRestartedHandlers.class, ON_DRIVER_RESTARTED)
171
172          // Evaluator handlers
173      .bindSetEntry(ServiceEvaluatorAllocatedHandlers.class, ON_EVALUATOR_ALLOCATED)
174      .bindSetEntry(ServiceEvaluatorCompletedHandlers.class, ON_EVALUATOR_COMPLETED)
175      .bindSetEntry(ServiceEvaluatorFailedHandlers.class, ON_EVALUATOR_FAILED)
176
177          // Task handlers
178      .bindSetEntry(ServiceTaskRunningHandlers.class, ON_TASK_RUNNING)
179      .bindSetEntry(ServiceTaskFailedHandlers.class, ON_TASK_FAILED)
180      .bindSetEntry(ServiceTaskMessageHandlers.class, ON_TASK_MESSAGE)
181      .bindSetEntry(ServiceTaskCompletedHandlers.class, ON_TASK_COMPLETED)
182      .bindSetEntry(ServiceTaskSuspendedHandlers.class, ON_TASK_SUSPENDED)
183
184          // Context handlers
185      .bindSetEntry(ServiceContextActiveHandlers.class, ON_CONTEXT_ACTIVE)
186      .bindSetEntry(ServiceContextClosedHandlers.class, ON_CONTEXT_CLOSED)
187      .bindSetEntry(ServiceContextMessageHandlers.class, ON_CONTEXT_MESSAGE)
188      .bindSetEntry(ServiceContextFailedHandlers.class, ON_CONTEXT_FAILED)
189
190      .build();
191}