Skip to content

Add quartz-2.2.3 documentation #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add quartz-2.2.3 documentation #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
46c633e
Add quartz-2.2.3 documentation (duplicate of quartz-2.2.2) (fixes #58)
samumbach Nov 23, 2020
c5bcffc
Update internal links: `.../quartz-2.2.2/...` => `.../quartz-2.2.3/...`
samumbach Nov 23, 2020
7e21a87
Link to 2.2.3 (latest 2.2.x release) in Quartz Documentation page sid…
samumbach Nov 23, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion _layouts/docs_page.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
<li id="site_mnu_docs_23x-stable" class="submenu"><a href="/documentation/quartz-{{ site.asciidoc_attributes.quartz-version-23x-stable}}">Quartz {{ site.asciidoc_attributes.quartz-version-23x-stable }}</a></li>


<li id="site_mnu_docs_2.2.2" class="submenu"><a href="/documentation/quartz-2.2.2">Quartz 2.2.2</a></li>
<li id="site_mnu_docs_2.2.3" class="submenu"><a href="/documentation/quartz-2.2.3">Quartz 2.2.3</a></li>
<li id="site_mnu_docs_2.1.7" class="submenu"><a href="/documentation/quartz-2.1.7">Quartz 2.1.7</a></li>
<li id="site_mnu_docs_2.0.2" class="submenu"><a href="/documentation/quartz-2.0.2">Quartz 2.0.2</a></li>
<li id="site_mnu_docs_1.8.6" class="submenu"><a href="/documentation/quartz-1.8.6">Quartz 1.8.6</a></li>
Expand Down
272 changes: 272 additions & 0 deletions documentation/quartz-2.2.3/configuration/ConfigDataSources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,272 @@
---
title: Configuration Reference
visible_title: "Quartz Configuration Reference"
active_sub_menu_id: site_mnu_docs_configuration
---
<div class="secNavPanel">
<a href="index.html">Contents</a> |
<a href="ConfigJobStoreCMT.html">&lsaquo;&nbsp;ConfigJobStoreCMT</a> |
<a href="ConfigJDBCJobStoreClustering.html">ConfigJDBCJobStoreClustering&nbsp;&rsaquo;</a>
</div>

# Configuration Reference

## Configure DataSources


If you're using JDBC-Jobstore, you'll be needing a DataSource for its use (or two DataSources, if you're using JobStoreCMT).

DataSources can be configured in three ways:

1. All pool properties specified in the quartz.properties file, so that Quartz can create the DataSource itself.
1. The JNDI location of an application server managed Datasource can be specified, so that Quartz can use it.
1. Custom defined *org.quartz.utils.ConnectionProvider* implementations.



It is recommended that your Datasource max connection size be configured to be at least the number of worker threads in the thread pool plus three.
You may need additional connections if your application is also making frequent calls to the scheduler API. If you are using JobStoreCMT,
the "non managed" datasource should have a max connection size of at least four.

Each DataSource you define (typically one or two) must be given a name, and the properties you define for each must contain that name, as shown below. The DataSource's "NAME" can be anything you want, and has no meaning other than being able to identify it when it is assigned to the JDBCJobStore.

### Quartz-created DataSources are defined with the following properties:

<table><thead>
<tr>
<th>Property Name</th>
<th>Required</th>
<th>Type</th>
<th>Default Value</th>
</tr>
</thead>

<tbody>
<tr>
<td>org.quartz.dataSource.NAME.driver</td>
<td>yes</td>
<td>String</td>
<td>null</td>
</tr>

<tr>
<td>org.quartz.dataSource.NAME.URL</td>
<td>yes</td>
<td>String</td>
<td>null</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.user</td>
<td>no</td>
<td>String</td>

<td>""</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.password</td>
<td>no</td>
<td>String</td>
<td>""</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.maxConnections</td>

<td>no</td>
<td>int</td>
<td>10</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.validationQuery</td>
<td>no</td>
<td>String</td>
<td>null</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.idleConnectionValidationSeconds</td>
<td>no</td>
<td>int</td>
<td>50</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.validateOnCheckout</td>
<td>no</td>
<td>boolean</td>
<td>false</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.discardIdleConnectionsSeconds</td>
<td>no</td>
<td>int</td>
<td>0 (disabled)</td>
</tr>

</tbody></table>

**org.quartz.dataSource.NAME.driver**

Must be the java class name of the JDBC driver for your database.

**org.quartz.dataSource.NAME.URL**

The connection URL (host, port, etc.) for connection to your database.

**org.quartz.dataSource.NAME.user**

The user name to use when connecting to your database.

**org.quartz.dataSource.NAME.password**

The password to use when connecting to your database.

**org.quartz.dataSource.NAME.maxConnections**

The maximum number of connections that the DataSource can create in it's pool of connections.

**org.quartz.dataSource.NAME.validationQuery**

Is an optional SQL query string that the DataSource can use to detect and replace failed/corrupt connections.
For example an oracle user might choose "select table_name from user_tables" - which is a query that should never
fail - unless the connection is actually bad.

**org.quartz.dataSource.NAME.idleConnectionValidationSeconds**

The number of seconds between tests of idle connections - only enabled if the validation query property is set.
Default is 50 seconds.

**org.quartz.dataSource.NAME.validateOnCheckout**

Whether the database sql query to validate connections should be executed every time a connection is retrieved
from the pool to ensure that it is still valid. If false, then validation will occur on check-in. Default is false.

**org.quartz.dataSource.NAME.discardIdleConnectionsSeconds**

Discard connections after they have been idle this many seconds. 0 disables the feature. Default is 0.


**Example of a Quartz-defined DataSource**

<pre>
org.quartz.dataSource.myDS.driver = oracle.jdbc.driver.OracleDriver
org.quartz.dataSource.myDS.URL = jdbc:oracle:thin:@10.0.1.23:1521:demodb
org.quartz.dataSource.myDS.user = myUser
org.quartz.dataSource.myDS.password = myPassword
org.quartz.dataSource.myDS.maxConnections = 30
</pre>


### References to Application Server DataSources are defined with the following properties:

<table><thead>
<tr>
<th>Property Name</th>
<th>Required</th>
<th>Type</th>
<th>Default Value</th>
</tr>
</thead>

<tbody>
<tr>
<td>org.quartz.dataSource.NAME.jndiURL</td>
<td>yes</td>
<td>String</td>
<td>null</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.java.naming.factory.initial</td>
<td>no</td>

<td>String</td>
<td>null</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.java.naming.provider.url</td>
<td>no</td>
<td>String</td>
<td>null</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.java.naming.security.principal</td>

<td>no</td>
<td>String</td>
<td>null</td>
</tr>
<tr>
<td>org.quartz.dataSource.NAME.java.naming.security.credentials</td>
<td>no</td>
<td>String</td>
<td>null</td>
</tr>

</tbody></table>


**org.quartz.dataSource.NAME.jndiURL**

The JNDI URL for a DataSource that is managed by your application server.

**org.quartz.dataSource.NAME.java.naming.factory.initial**

The (optional) class name of the JNDI InitialContextFactory that you wish to use.

**org.quartz.dataSource.NAME.java.naming.provider.url**


The (optional) URL for connecting to the JNDI context.

**org.quartz.dataSource.NAME.java.naming.security.principal**

The (optional) user principal for connecting to the JNDI context.

**org.quartz.dataSource.NAME.java.naming.security.credentials**

The (optional) user credentials for connecting to the JNDI context.

**Example of a Datasource referenced from an Application Server**

<pre>
org.quartz.dataSource.myOtherDS.jndiURL=jdbc/myDataSource
org.quartz.dataSource.myOtherDS.java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory
org.quartz.dataSource.myOtherDS.java.naming.provider.url=ormi:<span class="code-comment">//localhost
</span>org.quartz.dataSource.myOtherDS.java.naming.security.principal=admin
org.quartz.dataSource.myOtherDS.java.naming.security.credentials=123
</pre>





### Custom ConnectionProvider Implementations {#ConfigDataSources-CustomConnectionProviderImplementations}


<table><thead>
<tr>
<th>Property Name</th>
<th>Required</th>

<th>Type</th>
<th>Default Value</th>
</tr>
</thead>

<tbody>
<tr>
<td>org.quartz.dataSource.NAME.connectionProvider.class</td>
<td>yes</td>
<td>String (class name)</td>
<td>null</td>
</tr>
</tbody></table>

**org.quartz.dataSource.NAME.connectionProvider.class**

The class name of the ConnectionProvider to use. After instantiating the class, Quartz can automatically set configuration properties on the instance, bean-style.

**Example of Using a Custom ConnectionProvider Implementation**

<pre>
org.quartz.dataSource.myCustomDS.connectionProvider.class = com.foo.FooConnectionProvider
org.quartz.dataSource.myCustomDS.someStringProperty = someValue
org.quartz.dataSource.myCustomDS.someIntProperty = 5
</pre>
95 changes: 95 additions & 0 deletions documentation/quartz-2.2.3/configuration/ConfigJDBCJobStoreClustering.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
---
title: Configuration Reference
visible_title: "Quartz Configuration Reference"
active_sub_menu_id: site_mnu_docs_configuration
---
<div class="secNavPanel">
<a href="index.html">Contents</a> |
<a href="ConfigDataSources.html">&lsaquo;&nbsp;ConfigDataSources</a> |
<a href="ConfigTerracottaJobStore.html">ConfigTerracottaJobStore&nbsp;&rsaquo;</a>
</div>

# Configuration Reference

## Configure Clustering with JDBC-JobStore

Quartz's clustering features bring both high availability and scalability to your scheduler via fail-over and load balancing functionality.

<img src="quartz_cluster.png" align="absmiddle" border="0" />


Clustering currently only works with the JDBC-Jobstore (JobStoreTX or JobStoreCMT), and essentially works by having each node of the cluster share the same database.

Load-balancing occurs automatically, with each node of the cluster firing jobs as quickly as it can. When a trigger's firing time occurs, the first node to acquire it (by placing a lock on it) is the node that will fire it.

Only one node will fire the job for each firing. What I mean by that is, if the job has a repeating trigger that
tells it to fire every 10 seconds, then at 12:00:00 exactly one node will run the job, and at 12:00:10 exactly one
node will run the job, etc. It won't necessarily be the same node each time - it will more or less be random which
node runs it. The load balancing mechanism is near-random for busy schedulers (lots of triggers) but favors the
same node for non-busy (e.g. few triggers) schedulers.

Fail-over occurs when one of the nodes fails while in the midst of executing one or more jobs. When a node fails,
the other nodes detect the condition and identify the jobs in the database that were in progress within the failed node.
Any jobs marked for recovery (with the "requests recovery" property on the JobDetail) will be re-executed by the
remaining nodes. Jobs not marked for recovery will simply be freed up for execution at the next time a related trigger fires.

The clustering feature works best for scaling out long-running and/or cpu-intensive jobs (distributing the work-load
over multiple nodes). If you need to scale out to support thousands of short-running (e.g 1 second) jobs, consider
partitioning the set of jobs by using multiple distinct schedulers (including multiple clustered schedulers for HA).
The scheduler makes use of a cluster-wide lock, a pattern that degrades performance as you add more nodes (when going
beyond about three nodes - depending upon your database's capabilities, etc.).

Enable clustering by setting the "org.quartz.jobStore.isClustered" property to "true". Each instance in the cluster should use the same copy of the quartz.properties file. Exceptions of this would be to use properties files that are identical, with the following allowable exceptions: Different thread pool size, and different value for the "org.quartz.scheduler.instanceId" property. Each node in the cluster MUST have a unique instanceId, which is easily done (without needing different properties files) by placing "AUTO" as the value of this property. See the info about the configuration properties of JDBC-JobStore for more information.

<blockquote>
Never run clustering on separate machines, unless their clocks are synchronized using some form of time-sync service (daemon) that runs very regularly (the clocks must be within a second of each other). See <a href="http://www.boulder.nist.gov/timefreq/service/its.htm" >http://www.boulder.nist.gov/timefreq/service/its.htm</a> if you are unfamiliar with how to do this.
</blockquote>

<blockquote>
Never start (scheduler.start()) a non-clustered instance against the same set of database tables that any other instance is running (start()ed) against. You may get serious data corruption, and will definitely experience erratic behavior.
</blockquote>

**Example Properties For A Clustered Scheduler**

<pre>
#============================================================================
# Configure Main Scheduler Properties
#============================================================================

org.quartz.scheduler.instanceName = MyClusteredScheduler
org.quartz.scheduler.instanceId = AUTO

#============================================================================
# Configure ThreadPool
#============================================================================

org.quartz.threadPool.class = org.quartz.simpl.SimpleThreadPool
org.quartz.threadPool.threadCount = 25
org.quartz.threadPool.threadPriority = 5

#============================================================================
# Configure JobStore
#============================================================================

org.quartz.jobStore.misfireThreshold = 60000

org.quartz.jobStore.class = org.quartz.impl.jdbcjobstore.JobStoreTX
org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.oracle.OracleDelegate
org.quartz.jobStore.useProperties = <span class="code-keyword">false</span>
org.quartz.jobStore.dataSource = myDS
org.quartz.jobStore.tablePrefix = QRTZ_

org.quartz.jobStore.isClustered = <span class="code-keyword">true</span>
org.quartz.jobStore.clusterCheckinInterval = 20000

#============================================================================
# Configure Datasources
#============================================================================

org.quartz.dataSource.myDS.driver = oracle.jdbc.driver.OracleDriver
org.quartz.dataSource.myDS.URL = jdbc:oracle:thin:@polarbear:1521:dev
org.quartz.dataSource.myDS.user = quartz
org.quartz.dataSource.myDS.password = quartz
org.quartz.dataSource.myDS.maxConnections = 5
org.quartz.dataSource.myDS.validationQuery=select 0 from dual
</pre>
Loading