org.openmrs.module

Class ModuleUtil

java.lang.Object

org.openmrs.module.ModuleUtil

public class ModuleUtil
extends Object

Utility methods for working and manipulating modules

Method Summary

Modifier and Type	Method and Description
static Boolean	allowAdmin()
static Boolean	checkForModuleUpdates() Iterates over the modules and checks each update.rdf file for an update
protected static void	checkMandatoryModulesStarted() Looks at the <moduleid>.mandatory properties and at the currently started modules to make sure that all mandatory modules have been started successfully.
protected static void	checkOpenmrsCoreModulesStarted() Looks at the list of modules in ModuleConstants.CORE_MODULES to make sure that all modules that are core to OpenMRS are started and have at least a minimum version that OpenMRS needs.
static void	checkRequiredVersion(String version, String versionRange) This method is an enhancement of compareVersion(String, String) and adds support for wildcard characters and upperbounds.
static int	compareVersion(String version, String value) Compares version to value version and value are strings like 1.9.2.0 Returns 0 if either version or value is null.
static void	expandJar(File fileToExpand, File tmpModuleDir, String name, boolean keepFullPath) Expand the given fileToExpand jar to the tmpModuleFile directory If name is null, the entire jar is expanded.
static URL	file2url(File file) Utility method to convert a File object to a local URL.
static File	getDevelopmentDirectory(String moduleId) Gets the root folder of a module's sources during development
static List<String>	getMandatoryModules() Returns all modules that are marked as mandatory.
static Module	getModuleForPath(String path) Gets the module that should handle a path.
static File	getModuleRepository() Gets the folder where modules are stored.
static Collection<String>	getPackagesFromFile(File file) This loops over all FILES in this jar to get the package names.
static String	getPathForResource(Module module, String path) Takes a global path and returns the local path within the specified module.
static InputStream	getResourceFromApi(JarFile jarFile, String moduleId, String version, String resource) Get a resource as from the module's api jar.
static String	getURL(URL url) Downloads the contents of a URL and copies them to a string (Borrowed from oreilly)
static InputStream	getURLStream(URL url) Downloads the contents of a URL and copies them to a string (Borrowed from oreilly)
static boolean	ignoreCoreModules() Uses the runtime properties to determine if the core modules should be enforced or not.
static File	insertModuleFile(InputStream inputStream, String filename) Add the inputStream as a file in the modules repository
static boolean	isOpenmrsVersionInVersions(String... versions) Checks if the current OpenMRS version is in an array of versions.
static boolean	isVersionWithQualifier(String version) Checks for qualifier version (i.e "-SNAPSHOT", "-ALPHA" etc.
static boolean	matchRequiredVersions(String version, String versionRange) This method is an enhancement of compareVersion(String, String) and adds support for wildcard characters and upperbounds.
protected static InputStream	openConnectionCheckRedirects(URLConnection c) Convenience method to follow http to https redirects.
static org.springframework.context.support.AbstractRefreshableApplicationContext	refreshApplicationContext(org.springframework.context.support.AbstractRefreshableApplicationContext ctx)
static org.springframework.context.support.AbstractRefreshableApplicationContext	refreshApplicationContext(org.springframework.context.support.AbstractRefreshableApplicationContext ctx, boolean isOpenmrsStartup, Module startedModule) Refreshes the given application context "properly" in OpenMRS.
static void	shutdown() Stops the module system by calling stopModule for all modules that are currently started
static void	startup(Properties props) Start up the module system with the given properties.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

startup

public static void startup(Properties props)
                    throws ModuleMustStartException

Start up the module system with the given properties.

Parameters:

props - Properties (OpenMRS runtime properties)

Throws:

ModuleMustStartException

shutdown

public static void shutdown()

Stops the module system by calling stopModule for all modules that are currently started

insertModuleFile

public static File insertModuleFile(InputStream inputStream,
                                    String filename)

Add the inputStream as a file in the modules repository

Parameters:

inputStream - InputStream to load

Returns:

filename String of the file's name of the stream

isOpenmrsVersionInVersions

public static boolean isOpenmrsVersionInVersions(String... versions)

Checks if the current OpenMRS version is in an array of versions.

This method calls matchRequiredVersions(String, String) internally.

Parameters:

versions - the openmrs versions to be checked against the current openmrs version

Returns:

true if the current openmrs version is in versions otherwise false Should return false when versions is null Should return false when versions is empty Should return true if current openmrs version matches one element in versions Should return false if current openmrs version does not match any element in versions

matchRequiredVersions

public static boolean matchRequiredVersions(String version,
                                            String versionRange)

This method is an enhancement of compareVersion(String, String) and adds support for wildcard characters and upperbounds.

This method calls checkRequiredVersion(String, String) internally.

The require version number in the config file can be in the following format:

• 1.2.3
• 1.2.*
• 1.2.2 - 1.2.3
• 1.2.* - 1.3.*

Again the possible require version number formats with their interpretation:

• 1.2.3 means 1.2.3 and above
• 1.2.* means any version of the 1.2.x branch. That is 1.2.0, 1.2.1, 1.2.2,... but not 1.3.0, 1.4.0
• 1.2.2 - 1.2.3 means 1.2.2 and 1.2.3 (inclusive)
• 1.2.* - 1.3.* means any version of the 1.2.x and 1.3.x branch

Parameters:

version - openmrs version number to be compared

versionRange - value in the config file for required openmrs version

Returns:

true if the version is within the value Should allow ranged required version Should allow ranged required version with wild card Should allow ranged required version with wild card on one end Should allow single entry for required version Should allow required version with wild card Should allow non numeric character required version Should allow ranged non numeric character required version Should allow ranged non numeric character with wild card Should allow ranged non numeric character with wild card on one end Should return false when openmrs version beyond wild card range Should return false when required version beyond openmrs version Should return false when required version with wild card beyond openmrs version Should return false when required version with wild card on one end beyond openmrs version Should return false when single entry required version beyond openmrs version Should allow release type in the version Should match when revision number is below maximum revision number Should not match when revision number is above maximum revision number Should correctly set upper and lower limit for versionRange with qualifiers and wild card Should match when version has wild card plus qualifier and is within boundary Should not match when version has wild card plus qualifier and is outside boundary Should match when version has wild card and is within boundary Should not match when version has wild card and is outside boundary Should return true when required version is empty

checkRequiredVersion

public static void checkRequiredVersion(String version,
                                        String versionRange)
                                 throws ModuleException

This method is an enhancement of compareVersion(String, String) and adds support for wildcard characters and upperbounds.


The require version number in the config file can be in the following format:

• 1.2.3
• 1.2.*
• 1.2.2 - 1.2.3
• 1.2.* - 1.3.*

Again the possible require version number formats with their interpretation:

• 1.2.3 means 1.2.3 and above
• 1.2.* means any version of the 1.2.x branch. That is 1.2.0, 1.2.1, 1.2.2,... but not 1.3.0, 1.4.0
• 1.2.2 - 1.2.3 means 1.2.2 and 1.2.3 (inclusive)
• 1.2.* - 1.3.* means any version of the 1.2.x and 1.3.x branch

Parameters:

version - openmrs version number to be compared

versionRange - value in the config file for required openmrs version

Throws:

ModuleException - if the version is not within the value Should throw ModuleException if openmrs version beyond wild card range Should throw ModuleException if required version beyond openmrs version Should throw ModuleException if required version with wild card beyond openmrs version Should throw ModuleException if required version with wild card on one end beyond openmrs version Should throw ModuleException if single entry required version beyond openmrs version Should throw ModuleException if SNAPSHOT not handled correctly Should handle SNAPSHOT versions Should handle ALPHA versions

compareVersion

public static int compareVersion(String version,
                                 String value)

Compares version to value version and value are strings like 1.9.2.0 Returns 0 if either version or value is null.

Parameters:

version - String like 1.9.2.0

value - String like 1.9.2.0

Returns:

the value 0 if version is equal to the argument value; a value less than 0 if version is numerically less than the argument value; and a value greater than 0 if version is numerically greater than the argument value Should correctly comparing two version numbers Should treat SNAPSHOT as earliest version

isVersionWithQualifier

public static boolean isVersionWithQualifier(String version)

Checks for qualifier version (i.e "-SNAPSHOT", "-ALPHA" etc. after maven version conventions)

Parameters:

version - String like 1.9.2-SNAPSHOT

Returns:

true if version contains qualifier

getModuleRepository

public static File getModuleRepository()

Gets the folder where modules are stored. ModuleExceptions are thrown on errors

Returns:

folder containing modules Should use the runtime property as the first choice if specified Should return the correct file if the runtime property is an absolute path

file2url

public static URL file2url(File file)
                    throws MalformedURLException

Utility method to convert a File object to a local URL.

Parameters:

file - a file object

Returns:

absolute URL that points to the given file

Throws:

MalformedURLException - if file can't be represented as URL for some reason

expandJar

public static void expandJar(File fileToExpand,
                             File tmpModuleDir,
                             String name,
                             boolean keepFullPath)
                      throws IOException

Expand the given fileToExpand jar to the tmpModuleFile directory If name is null, the entire jar is expanded. Ifname is not null, then only that path/file is expanded.

Parameters:

fileToExpand - file pointing at a .jar

tmpModuleDir - directory in which to place the files

name - filename inside of the jar to look for and expand

keepFullPath - if true, will recreate entire directory structure in tmpModuleDir relating to name. if false will start directory structure at name Should expand entire jar if name is null Should expand entire jar if name is empty string Should expand directory with parent tree if name is directory and keepFullPath is true Should expand directory without parent tree if name is directory and keepFullPath is false Should expand file with parent tree if name is file and keepFullPath is true

Throws:

IOException

getURLStream

public static InputStream getURLStream(URL url)

Downloads the contents of a URL and copies them to a string (Borrowed from oreilly)

Parameters:

url -

Returns:

InputStream of contents Should return a valid input stream for old module urls

openConnectionCheckRedirects

protected static InputStream openConnectionCheckRedirects(URLConnection c)
                                                   throws IOException

Convenience method to follow http to https redirects. Will follow a total of 5 redirects, then fail out due to foolishness on the url's part.

Parameters:

c - the URLConnection to open

Returns:

an InputStream that is not necessarily at the same url, possibly at a 403 redirect.

Throws:

IOException

See Also:

getURLStream(URL)

getURL

public static String getURL(URL url)

Downloads the contents of a URL and copies them to a string (Borrowed from oreilly)

Parameters:

url -

Returns:

String contents of the URL Should return an update rdf page for old https dev urls Should return an update rdf page for old https module urls Should return an update rdf page for module urls

checkForModuleUpdates

public static Boolean checkForModuleUpdates()
                                     throws ModuleException

Iterates over the modules and checks each update.rdf file for an update

Returns:

True if an update was found for one of the modules, false if none were found

Throws:

ModuleException

allowAdmin

public static Boolean allowAdmin()

Returns:

true/false whether the 'allow upload' or 'allow web admin' property has been turned on

refreshApplicationContext

public static org.springframework.context.support.AbstractRefreshableApplicationContext refreshApplicationContext(org.springframework.context.support.AbstractRefreshableApplicationContext ctx)

See Also:

refreshApplicationContext(AbstractRefreshableApplicationContext, boolean, Module)

refreshApplicationContext

public static org.springframework.context.support.AbstractRefreshableApplicationContext refreshApplicationContext(org.springframework.context.support.AbstractRefreshableApplicationContext ctx,
                                                                                                                  boolean isOpenmrsStartup,
                                                                                                                  Module startedModule)

Refreshes the given application context "properly" in OpenMRS. Will first shut down the Context and destroy the classloader, then will refresh and set everything back up again.

Parameters:

ctx - Spring application context that needs refreshing.

isOpenmrsStartup - if this refresh is being done at application startup.

startedModule - the module that was just started and waiting on the context refresh.

Returns:

AbstractRefreshableApplicationContext The newly refreshed application context.

checkMandatoryModulesStarted

protected static void checkMandatoryModulesStarted()
                                            throws ModuleException

Looks at the <moduleid>.mandatory properties and at the currently started modules to make sure that all mandatory modules have been started successfully.

Throws:

ModuleException - if a mandatory module isn't started Should throw ModuleException if a mandatory module is not started

checkOpenmrsCoreModulesStarted

protected static void checkOpenmrsCoreModulesStarted()
                                              throws OpenmrsCoreModuleException

Looks at the list of modules in ModuleConstants.CORE_MODULES to make sure that all modules that are core to OpenMRS are started and have at least a minimum version that OpenMRS needs.

Throws:

ModuleException - if a module that is core to OpenMRS is not started Should throw ModuleException if a core module is not started

OpenmrsCoreModuleException

ignoreCoreModules

public static boolean ignoreCoreModules()

Uses the runtime properties to determine if the core modules should be enforced or not.

Returns:

true if the core modules list can be ignored.

getMandatoryModules

public static List<String> getMandatoryModules()

Returns all modules that are marked as mandatory. Currently this means there is a <moduleid>.mandatory=true global property.

Returns:

list of modules ids for mandatory modules Should return mandatory module ids

getModuleForPath

public static Module getModuleForPath(String path)

 Gets the module that should handle a path. The path you pass in should be a module id (in
 path format, i.e. /ui/springmvc, not ui.springmvc) followed by a resource. Something like
 the following:
   /ui/springmvc/css/ui.css

 The first running module out of the following would be returned:
   ui.springmvc.css
   ui.springmvc
   ui
 

Parameters:

path -

Returns:

the running module that matches the most of the given path Should handle ui springmvc css ui dot css when ui dot springmvc module is running Should handle ui springmvc css ui dot css when ui module is running Should return null for ui springmvc css ui dot css when no relevant module is running

getPathForResource

public static String getPathForResource(Module module,
                                        String path)

Takes a global path and returns the local path within the specified module. For example calling this method with the path "/ui/springmvc/css/ui.css" and the ui.springmvc module, you would get "/css/ui.css".

Parameters:

module -

path -

Returns:

local path Should handle ui springmvc css ui dot css example

getPackagesFromFile

public static Collection<String> getPackagesFromFile(File file)

This loops over all FILES in this jar to get the package names. If there is an empty directory in this jar it is not returned as a providedPackage.

Parameters:

file - jar file to look into

Returns:

list of strings of package names in this jar

getResourceFromApi

public static InputStream getResourceFromApi(JarFile jarFile,
                                             String moduleId,
                                             String version,
                                             String resource)

Get a resource as from the module's api jar. Api jar should be in the omod's lib folder.

Parameters:

jarFile - omod file loaded as jar

moduleId - id of the module

version - version of the module

resource - name of a resource from the api jar

Returns:

resource as an input stream or null if resource cannot be loaded Should load file from api as input stream Should return null if api is not found Should return null if file is not found in api

getDevelopmentDirectory

public static File getDevelopmentDirectory(String moduleId)

Gets the root folder of a module's sources during development

Parameters:

moduleId - the module id

Returns:

the module's development folder is specified, else null