//  ========================================================================
//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
//  ========================================================================
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================

[[ref-temporary-directories]]
=== Temporary Directories

Jetty itself has no temporary directories, but you can assign a directory for each web application, into which the WAR is unpacked, JSPs compiled on-the-fly, etc. 
If you do not assign a specific temporary directory, Jetty will create one as needed when your web application starts.
Whether you set the location of the temporary directory - or you let Jetty create one for you - you also have a choice to either keep or delete the temporary directory when the web application stops.

==== The default temp directory

By default, Jetty will create a temporary directory for each web application. The name of the directory will be of the form:

....
"jetty-"+host+"-"+port+"-"+resourceBase+"-_"+context+"-"+virtualhost+"-"+randomdigits+".dir"
....

For example:

....
jetty-0.0.0.0-8080-test.war-_test-any-8900275691885214790.dir
....

Where `0.0.0.0` is the host address, `8080` is the port, `test.war` is the resourceBase, `test` is the context path (with / converted to _), `any` is the virtual host, and `randomdigits` are a string of digits guaranteed to be unique.

Once the temp directory is created, it is retrievable as the value (as a File) of the context attribute `javax.servlet.context.tempdir.`

===== The location of the temp directory

By default, Jetty will create this directory inside the directory named by the `java.io.tmpdir` System property. 
You can instruct Jetty to use a different parent directory by setting the context attribute `org.eclipse.jetty.webapp.basetempdir` to the name of the desired parent directory. 
The directory named by this attribute _must_ exist and be __writeable__.

As usual with Jetty, you can either set this attribute in a context xml file, or you can do it in code. 

Here's an example of setting it in an xml file:

[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">

  <Set name="contextPath">/test</Set>
  <Set name="war">foo.war</Set>

  <Call name="setAttribute">
    <Arg>org.eclipse.jetty.webapp.basetempdir</Arg>
    <Arg>/home/my/foo</Arg>
  </Call>
</Configure>
----

The equivalent in code is:

[source, java, subs="{sub-order}"]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
context.setWar("foo.war");
context.setAttribute("org.eclipse.jetty.webapp.basetempdir", "/tmp/foo");
----

==== Setting a specific temp directory

There are several ways to use a particular directory as the temporary directory:

call WebAppContext.setTempDirectory(String dir)::
  Like before this can be accomplished with an xml file or directly in code. Here's an example of setting the temp directory in xml:
  +
[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">

  <Set name="contextPath">/test</Set>
  <Set name="war">foo.war</Set>

  <Set name="tempDirectory">/some/dir/foo</Set>
</Configure>
----

Here's an example of doing it with java code:

[source, java, subs="{sub-order}"]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
context.setWar("foo.war");
context.setTempDirectory(new File("/some/dir/foo"));
----

set the `javax.servlet.context.tempdir` context attribute::
  You should set this context attribute with the name of directory you want to use as the temp directory. Again, you can do this in xml:

[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">

  <Set name="contextPath">/test</Set>
  <Set name="war">foo.war</Set>

  <Call name="setAttribute">
    <Arg>javax.servlet.context.tempdir</Arg>
    <Arg>/some/dir/foo</Arg>
  </Call>

</Configure>
----

Or in java:

[source, java, subs="{sub-order}"]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
context.setWar("foo.war");
context.setAttribute("javax.servlet.context.tempdir", "/some/dir/foo");
----

Once a temporary directory has been created by either of these methods, a File instance for it is set as the value of the `javax.servlet.context.tempdir` attribute of the web application.

____
[NOTE]
Be wary of setting an explicit temp directory if you are likely to change the jars in WEB-INF/lib between redeployments.
There is a JVM bug concerning caching of jar contents: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4774421
____

==== The "work" directory

Mostly for backward compatibility, from jetty-9.1.1 onwards, it is be possible to create a directory named "work" in the `$\{jetty.base}` directory. 
If such a directory is found, it is assumed you want to use it as the parent directory for all of the temporary directories of the webapps in that `$\{jetty.base}`. 
Moreover, as has historically been the case, these temp directories inside the work directory are not cleaned up when jetty exists (or more correctly speaking, the `temp` directory corresponding to a context is not cleaned up when that context stops).

When a work directory is used, the algorithm for generating the name of the context-specific temp directories omits the random digit string. 
This ensures the name of the directory remains consistent across context restarts.

==== Persisting the temp directory

Sometimes you may find it useful to keep the contents of the temporary directory between restarts of the web application. 
By default, Jetty will _not_ persist the temp directory. 
To configure Jetty to keep it, use link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext.setPersistTempDirectory(true)].

____
[NOTE]
Be aware that if you call `setPersistTempDirectory(true)`, but let Jetty create a new temp directory each time (i.e. you do NOT set an explicit temp directory), then you will accumulate temp directories in your chosen temp directory location.
____
