public abstract class Microservice extends Object implements ConfigEventListener
A microservice defines a simple API for starting and stopping simple Java services contained in executable jars.
The general command for invoking these services is...
java -jar mymicroservice.jar [mymicroservice.cfg]
Your microservice class must be specified as the
getArgs()
- The command-line arguments passed to the jar file.
getConfig()
- An external INI-style configuration file.
getManifest()
- The manifest file for the main jar file.
start()
- Gets executed during startup.
stop()
- Gets executed when 'exit' is typed in the console or an external shutdown signal is received.
kill()
- Can be used to forcibly shut down the service. Doesn't get called during normal operation.
onStart()
- Gets executed before start()
.
onStop()
- Gets executed before stop()
.
onConfigChange(List)
- Gets executed after a config file has been modified.
createVarResolver()
- Creates the VarResolver
used to resolve variables in the config file
returned by getConfig()
.
Modifier | Constructor and Description |
---|---|
protected |
Microservice(String... args)
Constructor.
|
Modifier and Type | Method and Description |
---|---|
List<ConsoleCommand> |
createConsoleCommands()
Constructs the list of available console commands.
|
protected VarResolverBuilder |
createVarResolver()
Creates the
VarResolver used to resolve variables in the config file returned by getConfig() . |
protected void |
err(MessageBundle mb,
String messageKey,
Object... args)
Prints a localized message to STDERR.
|
Args |
getArgs()
Returns the command-line arguments passed into the application.
|
Config |
getConfig()
Returns the external INI-style configuration file that can be used to configure your microservice.
|
Map<String,ConsoleCommand> |
getConsoleCommands()
Returns the console commands associated with this microservice.
|
Scanner |
getConsoleReader()
Returns the console reader.
|
PrintWriter |
getConsoleWriter()
Returns the console writer.
|
static Microservice |
getInstance()
Returns the Microservice instance.
|
Logger |
getLogger()
Returns the logger for this microservice.
|
ManifestFile |
getManifest()
Returns the main jar manifest file contents as a simple
ObjectMap . |
VarResolver |
getVarResolver()
Returns the variable resolver for resolving variables in strings and files.
|
protected void |
initLogging()
Initialize the logging for this microservice.
|
Microservice |
join()
Joins the application with the current thread.
|
void |
kill()
Kill the JVM by calling
System.exit(2); . |
protected void |
log(Level level,
String message,
Object... args)
Logs a message to the log file.
|
void |
onConfigChange(List<ConfigEvent> events)
Called if one or more changes occur in the config file.
|
protected void |
onStart()
Called at the beginning of the
start() call. |
protected void |
onStop()
Called at the end of the
stop() call. |
protected void |
out(MessageBundle mb,
String messageKey,
Object... args)
Prints a localized message to the console writer.
|
Microservice |
setArgs(Args args)
Sets the arguments for this microservice.
|
void |
setConfig(Config cf)
Specifies the config for this microservice.
|
Microservice |
setConfig(String cfPath,
boolean create)
Specifies the path of the config file for this microservice.
|
Microservice |
setManifest(Class<?> c)
Same as
setManifest(Manifest) except finds and loads the manifest file of the jar file that the
specified class is contained within. |
Microservice |
setManifest(File f)
Same as
setManifest(Manifest) except specified through a File object. |
Microservice |
setManifest(Manifest mf)
Shortcut for calling
setManifest( . |
Microservice |
setManifest(ManifestFile mf)
Specifies the manifest file of the jar file this microservice is contained within.
|
Microservice |
setManifestContents(String... contents)
Convenience method for specifying the manifest contents directly.
|
Microservice |
start()
Start this application.
|
protected Microservice |
startConsole()
Start the console for this application.
|
Microservice |
stop()
Stop this application.
|
protected Microservice(String... args) throws Exception
args
- Command line arguments.Exception
public static Microservice getInstance()
This method only works if there's only one Microservice instance in a JVM.
Otherwise, it's just overwritten by the last call to Microservice(String...)
.
public Microservice setConfig(String cfPath, boolean create) throws IOException
If you do not specify the config file location, we attempt to resolve it through the following methods:
Main-Config
entry in the manifest file.
If this path does not exist, a FileNotFoundException
will be thrown from the start()
command.
cfPath
- The absolute or relative path of the config file.create
- Create the file if it doesn't exist.IOException
- If config file does not exist at the specified location or could not be read or created.public void setConfig(Config cf)
Note that if you use this method instead of setConfig(String,boolean)
, the config file will not use
the variable resolver constructed from createVarResolver()
.
cf
- The config file for this application, or public Microservice setManifest(ManifestFile mf)
If you do not specify the manifest file, we attempt to resolve it through the following methods:
mf
- The manifest file of this microservice.public Microservice setManifest(Manifest mf)
setManifest(new ManifestFile(mf))
.mf
- The manifest file of this microservice.public Microservice setManifestContents(String... contents) throws IOException
contents
- The lines in the manifest file.IOException
public Microservice setManifest(File f) throws IOException
setManifest(Manifest)
except specified through a File
object.f
- The manifest file of this microservice.IOException
- If a problem occurred while trying to read the manifest file.public Microservice setManifest(Class<?> c) throws IOException
setManifest(Manifest)
except finds and loads the manifest file of the jar file that the
specified class is contained within.c
- The class whose jar file contains the manifest to use for this microservice.IOException
- If a problem occurred while trying to read the manifest file.protected VarResolverBuilder createVarResolver()
VarResolver
used to resolve variables in the config file returned by getConfig()
.
The default implementation resolves the following variables:
SystemPropertiesVar
- $S{key[,default]}
EnvVariablesVar
- $E{key[,default]}
ArgsVar
- $A{key[,default]}
ManifestFileVar
- $MF{key[,default]}
IfVar
- $IF{arg,then[,else]}
SwitchVar
- $SW{arg,pattern1:then1[,pattern2:then2...]}
CoalesceVar
- $CO{arg1[,arg2...]}
PatternMatchVar
- $PM{arg,pattern}
NotEmptyVar
- $NE{arg}
UpperCaseVar
- $UC{arg}
LowerCaseVar
- $LC{arg}
ConfigVar
- $C{key[,default]}
Subclasses can override this method to provide their own variables.
VarResolver
.public Args getArgs()
This method can be called from the class constructor.
See Args
for details on using this method.
public Microservice setArgs(Args args)
args
- The arguments for this microservice.public Config getConfig()
The config location is determined in the following order:
Main-Config
entry in the microservice jar manifest file.
If all methods for locating the config fail, then this method returns
Subclasses can set their own config file by calling the setConfig(Config)
method.
String variables defined by createVarResolver()
are automatically resolved when using this method.
This method can be called from the class constructor.
public ManifestFile getManifest()
ObjectMap
.
This map consists of the contents of Manifest.getMainAttributes()
with the keys and entries converted to
simple strings.
This method can be called from the class constructor.
public VarResolver getVarResolver()
See the createVarResolver()
method for the list of available resolution variables.
public Logger getLogger()
public Microservice start() throws Exception
Default implementation simply calls onStart()
.
Overridden methods MUST call this method FIRST so that the onStart()
method is called.
Exception
protected Microservice startConsole() throws Exception
Note that this is typically started after all initialization has occurred so that the console output isn't polluted.
Exception
protected void initLogging() throws Exception
Subclasses can override this method to provide customized logging.
The default implementation uses the
Exception
public Microservice join() throws Exception
Default implementation is a no-op.
Exception
public Microservice stop()
Default implementation simply calls onStop()
.
Overridden methods MUST call this method LAST so that the onStop()
method is called.
public void kill()
System.exit(2);
.protected void onStart()
start()
call.
Subclasses can override this method to hook into the lifecycle of this application.
protected void onStop()
stop()
call.
Subclasses can override this method to hook into the lifecycle of this application.
public void onConfigChange(List<ConfigEvent> events)
Subclasses can override this method to listen for config file changes.
onConfigChange
in interface ConfigEventListener
events
- The list of changes in the config file.public final Map<String,ConsoleCommand> getConsoleCommands()
public List<ConsoleCommand> createConsoleCommands() throws Exception
By default, uses the
The order of the commands returned by this method is the order they will be listed
Exception
public Scanner getConsoleReader()
Subclasses can override this method to provide their own console input.
public PrintWriter getConsoleWriter()
Subclasses can override this method to provide their own console output.
protected void out(MessageBundle mb, String messageKey, Object... args)
Ignored if
mb
- The message bundle containing the message.messageKey
- The message key.args
- Optional MessageFormat
-style arguments.protected void err(MessageBundle mb, String messageKey, Object... args)
Ignored if
mb
- The message bundle containing the message.messageKey
- The message key.args
- Optional MessageFormat
-style arguments.protected void log(Level level, String message, Object... args)
level
- message
- The message text.args
- Optional MessageFormat
-style arguments.Copyright © 2018 Apache. All rights reserved.