//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

[[troubleshooting-locked-files-on-windows]]
=== Troubleshooting Locked Files on Windows

Jetty buffers static content for webapps such as HTML files, CSS files, images, etc.
If you are using NIO connectors, Jetty uses memory-mapped files to do this.
The problem is that on Windows, memory mapping a file causes the file to lock, so that you cannot update or replace the file.
Effectively this means that you have to stop Jetty to update a file.

==== Remedy

Jetty provides a configuration switch for the `DefaultServlet` that enables or disables the use of memory-mapped files.
If you are running on Windows and are having file-locking problems, you should set this switch to disable memory-mapped file buffers.
Use one of the following options to configure the switch.

===== Using override-web.xml

An <<override-web-xml, override-web.xml>> file can be placed in your webapp's `WEB-INF` directory to change the default setting of the `DefaultServlet` for memory-mapped file buffers. 
Create an `override-web.xml` file with appropriate headers for your version of the servlet specification, and place the following inside the `<web-app>` element:

[source, xml, subs="{sub-order}"]
----
 <servlet>
   <servlet-name>default</servlet-name>
   <init-param>
     <param-name>useFileMappedBuffer</param-name>
     <param-value>false</param-value>
   </init-param>
 </servlet>
----

===== Using a Context XML File

You can create or update a context xml file that configures your webapp to apply the setting to disable memory-mapped file buffers.
Add the following to your context xml file:

[source, xml, subs="{sub-order}"]
----
  <Call name="setInitParameter">
      <Arg>org.eclipse.jetty.servlet.Default.useFileMappedBuffer</Arg>
      <Arg>false</Arg>
  </Call>
----


===== Using the Jetty Maven Plugin

If you don't want to use either of the other two solutions, you can configure the plugin directly to disable memory-mapped file buffers.
Add the following to the plugin's configuration under the `<webApp>` element:

[source, xml, subs="{sub-order}"]
----
  <_initParams>
          <org.eclipse.jetty.servlet.Default.useFileMappedBuffer>false</org.eclipse.jetty.servlet.Default.useFileMappedBuffer>
  </_initParams>
----



==== Alternate Remedy

You can force a `WebAppContext` to always copy a web app directory on deployment.
The base directory of your web app (i.e. the root directory where your static content exists) will be copied to the link:#ref-temporary-directories[temp directory].
Configure this in an xml file like so:

[source, xml, subs="{sub-order}"]
----
<New id="myWebAppContext"  class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/</Set>
  <Set name="war">./webapps/fredapp</Set>
  <Set name="copyWebDir">true</Set>
  .
  .
</New>
----

____
[NOTE]
Be careful with this option when using an explicitly setlink:#ref-temp-directories[temp directory] name - as the name of the temp directory will not unique across redeployments, copying the static content into the same directory name each time may not avoid the locking problem.
____
