src.main.java.com.mgnt.lifecycle.management.backgroundrunner.package-info Maven / Gradle / Ivy

Go to download
/**
 * This package contains infrastructure that can run user implemented Task classes in a separate thread at configured
 * time interval. In order to create such task user will need to create a class that extends
 * {@link com.mgnt.lifecycle.management.backgroundrunner.BaseBackgroundRunnable} class and override 4 methods:
 * {@link com.mgnt.lifecycle.management.backgroundrunner.BaseBackgroundRunnable#initParamsForSpecificImplementation()}
,
 * {@link com.mgnt.lifecycle.management.backgroundrunner.BackgroundRunnable#getTaskExecutionInterval()}
,
 * {@link com.mgnt.lifecycle.management.backgroundrunner.BackgroundRunnable#setParamValue(com.mgnt.utils.entities.TimeInterval,
 * java.lang.String)}

 * and {@link java.lang.Runnable#run()}
. This infrastructure is intended for use with Spring framework although it may
 * be used in other environments as well. Before going any farther lets address a very glaring question. Why would anyone
 * want to use this infrastructure which already looks like requiring hard work if Spring provides an annotation
 * {@code @Scheduled} that can be used for any method and that would work just fine. Well The annotation
 * {@code @Scheduled} takes time interval property i.e. the time between 2 sequential executions in milliseconds or as
 * a cron expression. Neither of those formats are user friendly. Imagine that you need to run a task each 9 hours.
 * So you parameter that you will have to provide to {@code @Scheduled} annotation
 * would look like {@code @Scheduled(fixedRate = 32400000)}. (32400000 is number of milliseconds in 9 hours) This is
 * hardly intuitive... What if you could write {@code @Scheduled(fixedRate = 9h)}? Well, that would be great, but you
 * can not (at least with currently available latest versions). This is what this infrastructure provides. Especially
 * if you annotate one of your properties with annotation {@code @Value("${task.execution.interval}")} and then you will
 * have a properties file that will have a property {@code task.execution.interval=9h} instead of
 * {@code task.execution.interval=32400000}. So there is a trade-off here. This infrastructure definitely requires more effort
 * from a programmer then mere method annotation with {@code @Scheduled}, but provides very intuitive and humanly readable
 * way to define time interval properties. Internally this framework uses utility provided by this library to parse those
 * time intervals. (For details see {@link com.mgnt.utils.TextUtils#parseStringToTimeInterval(java.lang.String)}) Also
 * this infrastructure allows you to parse other time interval properties (if you class has any) with the same format.
 * 
 *     package {@code com.mgnt.lifecycle.management.backgroundrunner.example} contains working source code that demonstrates
 *     how this infrastructure is used. Assume that you have implemented your tasks
 *     {@link com.mgnt.lifecycle.management.backgroundrunner.example.TypeOneTask} and
 *     {@link com.mgnt.lifecycle.management.backgroundrunner.example.TypeTwoTask} (The same classes that are used in package
 *     {@code com.mgnt.lifecycle.management.backgroundrunner.example}). If you work in Spring environment you will need
 *     to annotate those classes with annotation {@code Component} (or define them as beans in your xml configuration files)
 *     and you will need to add one more declaration in your xml configuration file:

 *     {@code }
 *     The reason is that your tasks must be instantiated before instance of
 *     {@link com.mgnt.lifecycle.management.backgroundrunner.BackgroundThreadsRunner} is created by Spring
 * 
 * For the details on how to implement your tasks please refer to source code in the package
 * {@code com.mgnt.lifecycle.management.backgroundrunner.example} the code there is concise and well commented with
 * detailed explanation
 */
package com.mgnt.lifecycle.management.backgroundrunner;