001: /*
002: * Copyright 2004-2005 OpenSymphony
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy
006: * of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations
014: * under the License.
015: *
016: */
017:
018: /*
019: * Previously Copyright (c) 2001-2004 James House
020: */
021: package org.quartz.spi;
022:
023: import org.quartz.SchedulerConfigException;
024:
025: /**
026: * <p>
027: * The interface to be implemented by classes that want to provide a thread
028: * pool for the <code>{@link org.quartz.core.QuartzScheduler}</code>'s use.
029: * </p>
030: *
031: * <p>
032: * <code>ThreadPool</code> implementation instances should ideally be made
033: * for the sole use of Quartz. Most importantly, when the method
034: * <code>blockForAvailableThreads()</code> returns a value of 1 or greater,
035: * there must still be at least one available thread in the pool when the
036: * method <code>runInThread(Runnable)</code> is called a few moments (or
037: * many moments) later. If this assumption does not hold true, it may
038: * result in extra JobStore queries and updates, and if clustering features
039: * are being used, it may result in greater imballance of load.
040: * </p>
041: *
042: * @see org.quartz.core.QuartzScheduler
043: *
044: * @author James House
045: */
046: public interface ThreadPool {
047:
048: /*
049: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
050: *
051: * Interface.
052: *
053: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
054: */
055:
056: /**
057: * <p>
058: * Execute the given <code>{@link java.lang.Runnable}</code> in the next
059: * available <code>Thread</code>.
060: * </p>
061: *
062: * <p>
063: * The implementation of this interface should not throw exceptions unless
064: * there is a serious problem (i.e. a serious misconfiguration). If there
065: * are no immediately available threads <code>false</code> should be returned.
066: * </p>
067: *
068: * @return true, if the runnable was assigned to run on a Thread.
069: */
070: boolean runInThread(Runnable runnable);
071:
072: /**
073: * <p>
074: * Determines the number of threads that are currently available in in
075: * the pool. Useful for determining the number of times
076: * <code>runInThread(Runnable)</code> can be called before returning
077: * false.
078: * </p>
079: *
080: * <p>The implementation of this method should block until there is at
081: * least one available thread.</p>
082: *
083: * @return the number of currently available threads
084: */
085: int blockForAvailableThreads();
086:
087: /**
088: * <p>
089: * Called by the QuartzScheduler before the <code>ThreadPool</code> is
090: * used, in order to give the it a chance to initialize.
091: * </p>
092: */
093: void initialize() throws SchedulerConfigException;
094:
095: /**
096: * <p>
097: * Called by the QuartzScheduler to inform the <code>ThreadPool</code>
098: * that it should free up all of it's resources because the scheduler is
099: * shutting down.
100: * </p>
101: */
102: void shutdown(boolean waitForJobsToComplete);
103:
104: int getPoolSize();
105: }
|