Servlet 2.2 Facade

## Servlet Facades

### Goals

- Security. This is the first line of defense against not trusted code attempting to get access to internal tomcat objects. A servlet will only see objects that implement the API and provide no extra public methods that can be used.

- Decouple of the Servlet API implementation from the internal architecture of tomcat. Tomcat.core can use various optimizations and can have a design that is not directly controlled by the Servlet API requirements

- Performance. This is a direct consequence of decoupling - tomcat.core can be optimized without affecting the servlet side.

- Smooth evolution. Tomcat changes, and the separation of internals from the facade allowed an easy evolution. A side effect of the facade pattern is that it is possible to support multiple servlet APIs at the same time, allowing an easy migration when the spec is upgraded ( for example it may be possible to run both 2.2 and 2.3 servlets in the same engine, allowing a non-disruptive evolution ).

### Accessing tomcat internals

30. this is not final - need a lot of review and may change )

- Attribute access. A servlet can access a Context attribute named "org.apache.tomcat.facade" of type FacadeManager. The FacadeManager is the gate between internal objects and servlets - a servlet will be able to get an instance of FacadeManager only if the Context is marked as "trusted" ( by setting the "trusted" attribute in server.xml ). With JDK1.2 security we can implement finer control based on individual properties.

- It is possible to do security checks inside all methods in FacadeManager, allowing a finer access control. The FacadeManager may expose other internal of tomcat to trusted servlets.

- Internal servlets. All serlvets in org.apache.tomcat that extend org.apache.tomcat.servlet.TomcatInternalServlet will be initialized with the correct FacadeManager and will be able to do free conversions from Facade to internal objects. This is a hack to simplify the internal objects with minimal pain, after a "standard" access mode is stable enough.

### Security issues

- Getting an instance of FacadeManager.

- Extra checks in FacadeManagers:

- Context - a FacadeManager will verify if the Servlet object ( Request, Response, Context) are part of the same context as the servlet. That will prevent a servlet from accessing internal objects using a fake FacadeManager.

- Note that if a servlet has access to a tomcat internal object it may get access to potentially any other tomcat object.

- Object reuse. Reusing Facade objects can open a security hole - a servlet may keep references to HttpServletRequest objects and after a number of requests it will end up keeping references to all Facade objects ( there is no way to prevent that ). It will then be able to call for example getParameter() on all of those - accessing parameters of other servlets that happen to execute at that time. ClassLoader is not a good defense, since Facade objects can be loaded by the system class loader.

- JDK1.2 - it is possible to use the SecurityDomain and the context (thread) class loader to get informations about the running servlet and to do fine-access-control. A way to implement this without breaking compatibility with JDK1.1 is by using a different set of facades, or just by using a hook that will do the security checks ( better ).

- It is still possible for servlets to access core objects directly. This has to be fixed ASAP.

### Rules for this package:

- All classes except the "FacadeManager" have package-level access and are final. That means it is not possible to create or extend any of the facades unless you use the FacadeManager.

- The only public methods available in facades are those required by the servlet API.

- The facade objects will have minimal state, and will delegate most functionality to tomcat.core objects

- The only functionality present in facade is the "adapter" between the servlet API interfaces and tomcat internal interfaces. For example the I/O system in tomcat will be less dependent on Stream/Writer ( by using special hooks for char-to-byte conversion), but the facade must still prevent access to both Stream and Writer.

### Notes

This package implements the "Facade" and "Adapter" patterns.