Environment Module
 | Provides a simple abstraction of the execution environment |
| Type | JAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | XWiki 3.5M1+ |
Description
A lot XWiki modules can be used as Java libraries that can be used in one's own applications and thus run in various environments. However some of these libraries need to save temporary files or access configuration data that can be stored on the filesystem or even need to save data that should persist across restarts.
Thus XWiki offers this Environment abstraction that other modules can depend on whenever they need to interact with the Environment, making it possible to use them in various environment such a JavaSE, Servlet Container or other.
To use the Environment module just get the Environment component injected as in:
@Inject
private Environment environment
...
Note that you'll need to add a dependency on the Standard Environment JAR (for JavaSE) or the Servlet Environment JAR (for the Servlet environment).
Then you get access to the following Environment APIs:
{
/**
* Gets the directory for storing temporary data. The content of this directory may be deleted across restarts
* and thus is not a safe place to store permanent/important data.
*
* @return a {@link File} object pointing to a directory that the application can use for storing temporary files
*/
File getTemporaryDirectory();
/**
* Gets the root directory of a location for storing persisting data. Contrary to the Temporary Directory the
* content of this directory is guaranteed to persist across time.
*
* @return a {@link File} object pointing to the root folder of the permanent directory
*/
File getPermanentDirectory();
/**
* @param resourceName the full name of the resource to access (eg "/somefile.properties")
* @return the resource location as a {@link URL}
*/
URL getResource(String resourceName);
/**
* @param resourceName the full name of the resource to access (eg "/somefile.properties")
* @return the resource location as an {@link InputStream}
*/
InputStream getResourceAsStream(String resourceName);
}
Default Values
In order to make it easy to use we're providing default values for the various Environment directories, as follows:
- Temporary directory: We use the value of the java.io.tmpdir System property for the Standard Environment and the value of the javax.servlet.context.tempdir System property for the Servlet Environment.
- Permanent directory: We use the Temporary Directory location if not set
- Resources directory: We look for resources in the Class Loader that was used to load the Standard Environment component implementation class if not set. If set and the resource cannot be found we also fallback on that Class Loader.
To set different values, just look up the component implementations and use the setters available. For example:
environment.setTemporaryDirectory(...);
environment.setPermanentDirectory(...);
environment.setResourceDirectory(...);
environment.setResourceClassLoader(...);
Initializing XWiki when using its libraries standalone
If you're using XWiki's libraries in your own application you'll need to initialize the XWiki Component Manager.
However you'll also need to initialize the Environment to tell what temporary, permanent and resource directories to use and to make it easy to initialize both the XWiki Component Manager and the Environment we're providing a System helper class.
The simplest way to use it is simply:
There are also other initialize(...) signatures:
public static ComponentManager initialize(File permanentDirectory)
public static ComponentManager initialize(File permanentDirectory, File resourceDirectory)
public static ComponentManager initialize(File permanentDirectory, File resourceDirectory, File temporaryDirectory)
public static ComponentManager initialize(File permanentDirectory, File resourceDirectory, File temporaryDirectory, ClassLoader classLoader)
