it.sauronsoftware.cron4j
Class CronParser

java.lang.Object
  extended by it.sauronsoftware.cron4j.CronParser

public class CronParser
extends java.lang.Object

A parser for crontab-like formatted files and streams.

If you want to schedule a list of tasks declared in a crontab-like file you don't need the CronParser, since you can do it by adding the file to the scheduler, with the Scheduler.scheduleFile(File) method.

Consider to use the CronParser if the Scheduler.scheduleFile(File) method is not enough for you. In example, you may need to fetch the task list from a remote source which is not representable as a File object (a document on a remote server, a DBMS result set and so on). To solve the problem you can implement your own TaskCollector, getting the advantage of the CronParser to parse easily any crontab-like content.

You can parse a whole file/stream, but you can also parse a single line.

A line can be empty, can contain a comment or it can be a scheduling line.

A line containing no characters or a line with only space characters is considered an empty line.

A line whose first non-space character is a number sign (#) is considered a comment.

Empty lines and comment lines are ignored by the parser.

Any other kind of line is parsed as a scheduling line.

A valid scheduling line respects the following structure:

 scheduling-pattern [options] command [args]
 

After the scheduling pattern item, other tokens in each line are space separated or delimited with double quotation marks (").

Double quotation marks delimited items can take advantage of the following escape sequences:

The options token collection can include one or more of the following elements:

It is also possible to schedule the invocation of a method of a Java class in the scope of the parser ClassLoader. The method has to be static and it must accept an array of strings as its sole argument. To invoke a method of this kind the syntax is:

 scheduling-pattern java:className#methodName [args]
 

The #methodName part can be omitted: in this case the main(String[]) method will be assumed.

Please note that static methods are invoked within the scheduler same JVM, without spawning any external process. Thus IN, OUT, ERR, ENV and DIR options can't be applied.

Invalid scheduling lines are discarded without blocking the parsing procedure, but an error message is printed in the application standard error channel.

Valid examples:

 0 5 * * * sol.exe
 0,30 * * * * OUT:C:\ping.txt ping 10.9.43.55
 0,30 4 * * * "OUT:C:\Documents and Settings\Carlo\ping.txt" ping 10.9.43.55
 0 3 * * * ENV:JAVA_HOME=C:\jdks\1.4.2_15 DIR:C:\myproject OUT:C:\myproject\build.log C:\myproject\build.bat "Nightly Build"
 0 4 * * * java:mypackage.MyClass#startApplication myOption1 myOption2
 

Since:
2.0
Author:
Carlo Pelliccia

Method Summary
static TaskTable parse(java.io.File file)
           Builds a task list reading it from a file.
static TaskTable parse(java.io.InputStream stream)
           Builds a task list reading it from an input stream.
static TaskTable parse(java.io.Reader reader)
           Builds a task list reading it from a reader.
static TaskTable parse(java.net.URL url)
           Builds a task list reading it from an URL.
static void parseLine(TaskTable table, java.lang.String line)
          Parses a crontab-like line.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

parse

public static TaskTable parse(java.io.File file)
                       throws java.io.IOException

Builds a task list reading it from a file.

The file is treated as UTF-8. If your source file is not UTF-8 encoded establish by yourself a Reader using the right charset and pass it to the parse(Reader) method.

Syntax and semantics errors in the source file are not blocking. Invalid lines are discarded, and they cause just a stack trace to be printed in the standard error channel as a notification.

Parameters:
file - The file.
Returns:
The task table parsed from the file.
Throws:
java.io.IOException - I/O error.

parse

public static TaskTable parse(java.net.URL url)
                       throws java.io.IOException

Builds a task list reading it from an URL.

Contents fetched from the URL are treated as UTF-8. If your source is not UTF-8 encoded establish by yourself a Reader using the right charset and pass it to the parse(Reader) method.

Syntax and semantics errors in the retrieved document are not blocking. Invalid lines are discarded, and they cause just a stack trace to be printed in the standard error channel as a notification.

Parameters:
url - The URL.
Returns:
The task table parsed from the contents fetched from the given URL.
Throws:
java.io.IOException - I/O error.

parse

public static TaskTable parse(java.io.InputStream stream)
                       throws java.io.IOException

Builds a task list reading it from an input stream.

The stream is treated as UTF-8. If your source is not UTF-8 encoded establish by yourself a Reader using the right charset and pass it to the parse(Reader) method.

Syntax and semantics errors in the source stream are not blocking. Invalid lines are discarded, and they cause just a stack trace to be printed in the standard error channel as a notification.

Parameters:
stream - The input stream.
Returns:
The task table parsed from the stream contents.
Throws:
java.io.IOException - I/O error.

parse

public static TaskTable parse(java.io.Reader reader)
                       throws java.io.IOException

Builds a task list reading it from a reader.

Syntax and semantics errors in the source reader are not blocking. Invalid lines are discarded, and they cause just a stack trace to be printed in the standard error channel as a notification.

Parameters:
reader - The reader.
Returns:
The task table parsed from the contents in the reader.
Throws:
java.io.IOException - I/O error.

parseLine

public static void parseLine(TaskTable table,
                             java.lang.String line)
                      throws java.lang.Exception
Parses a crontab-like line.

Parameters:
table - The table on which the parsed task will be stored, by side-effect.
line - The crontab-like line.
Throws:
java.lang.Exception - The supplied line doesn't represent a valid task line.