Javadocs.

jetty-fcgi/fcgi-server/src/main/java/org/eclipse/jetty/fcgi/server/proxy/FastCGIProxyServlet.java

@@ -34,6 +34,29 @@ import org.eclipse.jetty.http.HttpFields;
 import org.eclipse.jetty.http.HttpScheme;
 import org.eclipse.jetty.proxy.ProxyServlet;
 
+/**
+ * Specific implementation of {@link ProxyServlet.Transparent} for FastCGI.
+ * <p />
+ * This servlet accepts a HTTP request and transforms it into a FastCGI request
+ * that is sent to the FastCGI server specified in the <code>proxyTo</code>
+ * init-param.
+ * <p />
+ * This servlet accepts two additional init-params:
+ * <ul>
+ *     <li><code>scriptRoot</code>, mandatory, that must be set to the directory where
+ *     the application that must be served via FastCGI is installed and corresponds to
+ *     the FastCGI DOCUMENT_ROOT parameter</li>
+ *     <li><code>scriptPattern</code>, optional, defaults to <code>(.+?\.php)</code>,
+ *     that specifies a regular expression with at least 1 and at most 2 groups that specify
+ *     respectively:
+ *     <ul>
+ *         <li>the FastCGI SCRIPT_NAME parameter</li>
+ *         <li>the FastCGI PATH_INFO parameter</li>
+ *     </ul></li>
+ * </ul>
+ *
+ * @see TryFilesFilter
+ */
 public class FastCGIProxyServlet extends ProxyServlet.Transparent
 {
     public static final String SCRIPT_ROOT_INIT_PARAM = "scriptRoot";

jetty-fcgi/fcgi-server/src/main/java/org/eclipse/jetty/fcgi/server/proxy/TryFilesFilter.java

@@ -27,6 +27,7 @@ import java.nio.file.Paths;
 import javax.servlet.Filter;
 import javax.servlet.FilterChain;
 import javax.servlet.FilterConfig;
+import javax.servlet.ServletContext;
 import javax.servlet.ServletException;
 import javax.servlet.ServletRequest;
 import javax.servlet.ServletResponse;
@@ -34,7 +35,34 @@ import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
 /**
- * Inspired by nginx's try_files functionality
+ * Inspired by nginx's try_files functionality.
+ * <p />
+ * This filter accepts the <code>files</code> init-param as a list of space-separated
+ * file URIs. The special token <code>$path</code> represents the current request URL's
+ * path (the portion after the context path).
+ * <p />
+ * Typical example of how this filter can be configured is the following:
+ * <pre>
+ * &lt;filter&gt;
+ *     &lt;filter-name&gt;try_files&lt;/filter-name&gt;
+ *     &lt;filter-class&gt;org.eclipse.jetty.fcgi.server.proxy.TryFilesFilter&lt;/filter-class&gt;
+ *     &lt;init-param&gt;
+ *         &lt;param-name&gt;files&lt;/param-name&gt;
+ *         &lt;param-value&gt;maintenance.html $path index.php?p=$path&lt;/param-value&gt;
+ *     &lt;/init-param&gt;
+ * &lt;/filter&gt;
+ * </pre>
+ * For a request such as <code>/context/path/to/resource.ext</code>, this filter will
+ * try to serve the <code>/maintenance.html</code> file if it finds it; failing that,
+ * it will try to serve the <code>/path/to/resource.ext</code> file if it finds it;
+ * failing that it will forward the request to <code>index.php?p=/path/to/resource.ext</code>.
+ * The last file URI specified in the list is therefore the "fallback" to which the request
+ * is forwarded to in case no previous files can be found.
+ * <p />
+ * The files are resolved using {@link ServletContext#getResource(String)} to make sure
+ * that only files visible to the application are served.
+ *
+ * @see FastCGIProxyServlet
  */
 public class TryFilesFilter implements Filter
 {