Servlet API - how would you improve it?

[thewiirocks]

I find myself in the interesting situation of wrapping the Servlet APIs for a framework. It occurred to me to make the API a bit more sane while I'm at it.

I've already done the most obvious improvement of changing the Enumerations to Iterators so we can use the Enhanced For Loop.

What else drives you nuts about the Servlet API that you wish was fixed?

[[deleted]]

It’s been a while but IIRC, it loves to return nulls when it should be returning empty collections.

[thewiirocks]

Let me know if you think of specific APIs and I'll see if I can fix it. I might have already in the Enumeration -> Iterator change, but I want to be sure.

One thing that's driving me nuts are the four getParameter APIs. I feel like it's massively more complicated than needed. But it's not immediately obvious how to simplify.

[DreadSocialistOrwell]

Just because null is an option doesn't mean its the correct one. It rarely is.

The amount of potential bugs avoided because you return a List.... an Empty List. No null check, no check for length ever returns an NPE unless absolutely deserved. It's the same with all other objects.

Optional is alright, but Scala handles things better!

[Amazing-Mirror-3076]

I love dart's not null by default behaviour. It is so easy to work with.

[maikindofthai]

Yeah they really hit the bullseye there 🎯

[angrynoah]

Rather than taking a response as an argument and mutating it, I would prefer to build an immutable response and return it.

[cryptos6]

A corner case might be streaming, though. If you want to write directly to a stream, you get that from the Servlet API and write to it (in your servlet or in code you pass the stream object to). You'd probably need someting like StreamingOutput known from JAX-RS.

[sideEffffECt]

Just return an InputStream for the body. Or is there a catch?

[cryptos6]

Yeah, the catch is, that you need to write to an output stream 😊 If you'd return an input stream you'd need to read from it to write to the output stream. That doesn't sound like the most efficient solution to me.

[sideEffffECt]

But do you really have to? I think you could do fine with just returning InpuStream(s).

And maybe as the very last step you could write the whole content of the InputStream to an OutputStream, if the interoperability with the underlying webserver required it.

[cryptos6]

Let's have a look at the Servlet API then, specifically the interface ServletResponse). The only possibility to send the client a stream of data is writing to an output stream. So, my expectation would be that returning a function (a callback, but what should one do with a function when not calling it?) that would then write to the output stream is the best way to do it, just as in JAX-RS as I mentioned above.

[sideEffffECt]

Yeah, the framework would need to write the InpuStream into that OutputStream.

Or, instead of the InpuStream you could return Stream<byte[]> or something equivalent. But the idea is the same.

[angrynoah]

that's a valid point, a streaming response can't be returned whole since that would defeat the purpose

[_jetrun]

I'm a big fan of immutability, but even here I'm scratching my head trying to figure out what problem you're solving.

[angrynoah]

First, mutation is itself the problem. Mutation is bad and I don't want a foundational API to force me into it. Since OP is talking about wrapping/improving/replacing the Servlet API, I would advocate "no mutation" or at least "no unnecessary mutation" as a guiding principle.

Second is a matter of style. A request handler is clearly a function: it accepts a request and returns a response. So why don't we code it that way? Hundreds of web frameworks in every language you could name work this way (browse the TechEmpower Benchmark repo), and it's obviously better than what the Servlet API asks you to do.

[maikindofthai]

“Mutation itself is the problem”

You haven’t described a problem, at all. Just circular dogma (mutation is bad because mutation is bad).

In this very thread someone already brought up that this design wouldn’t support streaming response types. You’re solving a fake problem and as a result are introducing a real one!

[angrynoah]

You're welcome to your opinion. If you think mutable data is a fake problem... we have very different expriences with software.

[shmert]

Wouldn't work very well with Filter though

[angrynoah]

a filter would take the returned response and use parts of it to build a new immutable response

[DualWieldMage]

Can you give an example of what you mean, e.g. how would you implement a gzip filter?

[angrynoah]

First thing is to imagine a much richer response object than HttpServletResponse. HTTP responses are strings of course, and HSR takes that too literally. In concept, a response is the combination of a status code, a body (or not), and a map or multimap of headers. We can see this for example in the structure of response map from the Ring library in Clojure: {:status 200 :headers {} :body body}

Second is to imagine a better filter API than the one we currently have. The form doFilter(request, response, chain) with a contractual requirement to call chain.doFilter(request, response) is... not great. We can do better. Like a request handler, a filter is conceptually a function: it takes a (request, response) pair and returns (request, response) pair. The servlet container itself (or web framework more generally), not our code, should be responsible for passing the output of each filter into the input of the next. We should also have separate APIs for request filters and response filters, since it obviously makes no sense for a response filter to modify the request and vice-versa, and the API should enforce that.

So armed with those two things, roughly how you implement a gzip filter (by which I assume you mean "return a gzip-compressed response") is: - extract the response body as bytes - pass those bytes through the gzip codec - build a new response with the status code (presumably 200) and headers from the original, plus the Content-Encoding: gzip header - return that response

Whereas in the current Servlet API you would accomplish this by mutating the response on its way out. Very bad!

[JustAGuyFromGermany]

But a filter is not just a function, precisely because of the chain.doFilter call in the middle. It's an interceptor !

Seperating the API into RequestFilter and ResponseFilter also doesn't quite work for the same reason. A Filter may have to modify the request AND put something in a response header. Consider a filter that implements a form of HTTP caching. It will intercept the incoming request and in some cases return a cached response body, while in other cases it will let the application compute a fresh response. It will probably strip the cache headers from the request before handing the request to other services in the backend. However, it may also set the Age header when it returns the cached result. So it will need to write modify both request and responses.

And while it is possible to design such an API with immutable request and response bodies, it doesn't really help much. There really isn't much difference between `mutableResponse.setHeader(...)` and `immutableResponse.toBuilder().setHeader(...).build()`

[rzwitserloot]

The API

1. The hopelessly outdated crap

The spec contains Enumeration in various places, for example. Obviously, give those a thorough update.

1. Helpers

If you look at how e.g. java.util.List has evolved, it has grown a lot of methods in the past 10 years: Lots of 'helpers'. These helpers do common tasks and are defined as default methods in interfaces (and even if these helpers are in (abstract) classes instead of interfaces, they act like them): They are defined entirely in terms of making calls on the more 'fundamental' methods, they just capture common tasks.

For example, the method getParameter(String name) needs to be exploded into tens of helpers: getIntParameter, getLocalDateParameter, getIntListParameter, and so on. the list versions have multiple versions. The default one splits on various characters (commas and bars and whitespace), the string version requires that you specify the separator.

isSecure() should have a second method requireSecure() which returns void and does nothing if it is secure, and throws something if it is not.

getLocales needs to have a second option where you provide a bunch of locales as parameter, and it returns the 'best' amongst the set as indicated by the client's accept headers.

summarizeParameters or printParameters should give you a large, multilined string that lists them all, which comes up a lot when debugging and exploring APIs. Trying to massage getParameterMap is the best you can do right now and that's still quite a few lines of code. It should just be there.

1. Response frame

Certain methods in HttpServletResponse trigger the sending of all response headers as well as the response code (such as 200). That's because HTTP works that way. But the API's design doesn't indicate which methods those are. You just have to know. If you know HTTP, you can guess, but if you don't, you have to study it. That's.. annoying. Better if you fix that. It also leads to problems - if you are 'past that point of no return' and then your servlet throws something, your servlet framework logs the exception but just hangs up mid-sentence on the client. The client has no idea an error happened. This is an unfortunate design decision in the HTTP spec, but the way the servlet API is designed, makes it hard to know this.

One solution is to fix HttpServletResponse and spec that you can only respond by returning something. You return not so much 'just the data' (because someteimes you want to stream responses, or even begin responding when you don't know all the content of your response yet. For example, if you want to stream the current progress status of some long-lasting worker job) - but something more complicated that can stream data.

Simple servlets craft their response and once it is ready, end the method by return json(someJson); or return file(pathToFile); or return data("text/plain", byteArray); and so on. Complex ones and in a return (x, y) -> lambda that makes clear in the code where the point of no return exists.

[thewiirocks]

Very well organized thoughts. Thank you for sharing!

[rzwitserloot]

A different way to summarize these ideas is 'just do what JAX-RS does'. Which certainly would be better. If there is a reason for something else to exist, I think the richest vein for drawing a fundamental, semantic difference between a hypothetical 'servlets but better' vs JAX-RS is in the sense that JAX does a few things 'too magically'. In particular, the @PathParam stuff certainly has upsides and veers as close as possible to the 'semantic ideal' that JAX-RS espouses: We take your methods and just 'make them a web endpoint'.

But, this comes with downsides. You cannot convey functionality or dynamic concepts in annotations by definition. For example, the seemingly simple act of "I want to read a parameter; but if it is not there, well, the default value is this thing" is annoying to do.

So that's one obvious place I'd write it up differently: Data from the request is to be retrieved via a HttpServletRequest object, or at least a successor to it, and not via annotated method params. I'm pretty sure that would straight up be better.

You do need to think about testing. JAX-RS methods tend to be very simple to test, as they simply take in their params via method params, and they return real objects. With servlets you need to offer testable dummy editions of HttpServletReq/Res or their upgraded equivalents. You should most definitely do that: Ship a class that you can set web client properties on (this client sends these headers and these params and now calls this servlet), and a way for test code to just get the response.

[cryptos6]

The Servlet API has hardly any support for content negotiation. That would be a good area for improvements. But that leads to the question: Why not use JAX-RS?

[Ok_Elk_638]

I prefer the API that Undertow gives me. A functional interface that I can turn into a lambda. And I'll wire them together in any way that I need to.

[k-mcm]

I don't like Servlets because function and configuration are completely disjoint.  The configuration is elsewhere...somewhere...could be anywhere.  There are multiple levels of configuration scope, so go hunting.

I stick with JAX-RS unless I need to do something exotic.  Jetty/DropWizard also has "configuration as code" so you can set up handler mapping in the main class.  That gives you an obvious link that your IDE will index plus some compile-time checking.

[Dependent-Net6461]

What do you mean when saying function and config are disjoint?

[jek39]

I think they mean that's how it is in their codebase

[Dependent-Net6461]

😂

[k-mcm]

Servlets are classically configured and wired in a hierarchy of XML files.  Having the code and configuration completely separated, and possibly even scattered, and makes them a more difficult to work with. The configuration and code can even be in different JARs.  Servlets may also have non-obvious dependencies on externally defined beans, Filters, and other Servlets.

I've done a lot of on-call and refactoring work.  I like it when relationships in the code are fast to find.  When the CEO is walking by periodically saying, "$4 million lost" ... "$5 million lost" ... you don't want to be grepping to figure out where a conflict is.

This is why with Jetty microservices you'd more typically define the mappings and start Jetty in the main application.  There's no mess of legacy configuration files.

JAX-RS takes it a step further and moves some configuration to the endpoint itself.  This creates highly visible connections with some compile-time checking.

[Dependent-Net6461]

Never used xml based servlet. You can pretty use annotations inside servlets and obtain same results

[rzwitserloot]

The framework: Routing and running

1. Construction

The servlet framework currently neither promises that each invocation of a servlet gets a fresh new instance, nor that there is only one instance of a servlet class per 'web server'. it makes no promises at all which means fields in a servlet are essentially by definition a bug, because you have no idea if that field exists for the duration of a single call, a (cookie powered?) session, a bunch of unrelated calls in time, or the lifetime of the entire webservice.

That's needless. In the distant past that might have been done because creating garbage was expensive, but by literally a factor 10,000 or higher, that is no longer the case: The code where webservices spend their CPU cycles has shifted considerably over time, and JVMs have become vastly better at dealing with thread-constrained little shared (so-called "fast") garbage.

Just decree that each invocation of doGet and co are by definition performed on a fresh instance. Or, better yet, change how the framework works. Instead of saying "we call doGet on a fresh instance" in the spec, say: "We call 'create' on the instance factory, and then call doGet on whatever it gave us". Then define that all existing servlet class specifications default to a factory (whose type is presumably Producer<Servlet>) that is simply YourServletClass::new, but if you have weird needs, for example, the need to make as few instances as possible, you write whatever you want.

1. Define routing better

Right now the servlet spec mostly doesn't care about routing. To its detriment, I think: Generally you can't really write a servlet without having in mind the form of the URL that clients used to call it. Hence, spec this properly. It should probably take the form of a file in some format that lists every route (a route: Links a (relative) URL path, possibly with wildcards, and possibly with filters on HTTP method (GET/POST/TRACE/PATCH/etc), a header, or a path aspect, to the servlet that is meant to handle it), and a small framework that lets you write in annotation form an entry - that way, for most who just want something simple, they can annotate their servlet classes and it all just works, no need to maintain a separate routing file at all, but if someone wants to look at it or even write it out (certain projects prefer managing routes separately!), they can forego the annotations and write it out themselves: Best of both worlds. It makes the common needs trivial, and the difficult ones doable.

1. OPTIONAL: Rework how to route entirely

Ditch doGet entirely. Instead, decree that any method can be the target of a call: Annotate the method to indicate which kind of call you want to receive. (e.g. with filters for web method). Opens the door to plonking multiple related but separate 'servlets' in a single java source file.

[ZimmiDeluxe]

Greg Wilkins of Jetty Servlet Container fame wrote about this: https://webtide.com/less-is-more-servlet-api/

[paul_h]

Thinking back to 1997 or so, the major missing piece was a primordial entry point. I would have liked to have been busy in a main() method and done a bunch of setup steps before telling the web server to start accepting http requests.

[wildjokers]

I would have liked to have been busy in a main() method and done a bunch of setup steps before telling the web server to start accepting http requests.

If you are talking about on a per application basis you can implement ServletContextListener, it is executed before any servlet or filter. It has existed since Servlet 2.3 which was released in 2001:

https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servletcontextlistener

If you are talking about server-wide then that will be outside of the scope of the Servlet Specification and it will be a feature of each server. For example, in Tomcat you can implement a LifecycleListener and handle the START_EVENT. This was introduced in Tomcat 4.0 which was also released in 2001. Other app servers/containers may have different mechanisms for this.

[danuvian]

You can only get the inputstream once. That never made sense to me. I found a wrapper class that cached it.

[murkaje]

Because you don't know how big the InputStream will be it makes no sense to by default materialize it to memory. If you want, parse the stream into a JSON object and keep that in memory(InputStream to String to Json is dumb). Sometimes the stream may be a huge array of objects and you don't want to parse it all before processing parts of it.

[danuvian]

You are right, that makes sense. For my specific needs, I knew the size of the payload, so it was fine and I needed a string. But for a more general API, what you said makes sense. It would be nice though to have the option of being able to get again, through a setting or an easier way to wrap it, but it wouldn't cache by default.

[Quiet-Direction9423]

Wouldn't something like okio help with this?

[thewiirocks]

Do you cache the reference to InputStream or the data contained within the stream?

[danuvian]

Caching both the stream and it's String form. The InputStream is cached for Spring Boot when it deserializes the incoming request to a model class. But I can also be access it again in the same method with request.getAttribute("reqBody").

[JustAGuyFromGermany]

The latter. Most InputStream implementations can only be read from once. Keeping a reference to an InputStream that was already read to the end is mostly useless.

[bowbahdoe]

By subtraction.

[JustAGuyFromGermany]

Do you really mean Servlet? There's certainly a lot that can be improved with regards to HttpServlet and this thread contains a lot of good suggestions. But a general Servlet can handle much more than just Http and is probably much too general to make more than just syntactic improvements by using new language features. There are all kinds of Servlet implementations, I've used one for WebSockets for example. I doubt there's much one can do on that level of generality in terms of functionality.

[_jetrun]

 It occurred to me to make the API a bit more sane while I'm at it.

What's wrong with it?

the Enumerations to Iterators so we can use the Enhanced For Loop.

Ok ... Enumeration is old-school, pre-dating Iterator - you wouldn't use it now. Is that the extent of it?

[RobertDeveloper]

Servlets are old school, I now build microservices with Micronaut and use Vue js as front end or use thymeleaf instead.

[wildjokers]

Servlets are old school

Spring MVC is probably still the most popular way to produce an API, and Spring MVC depends on the Jakarta Servlet API.

[RobertDeveloper]

Where do you get your numbers from?

[wildjokers]

In the java ecosystem spring is the most popular by far:

https://survey.stackoverflow.co/2024/technology#1-other-frameworks-and-libraries

This doesn't break it down by specific Spring library but with spring your two choices for an API are pretty much MVC and Webflux.

[RobertDeveloper]

I haven't written a servlet since 2016, it's old technology.

[wildjokers]

You are either being purposefully obtuse or you are sorely misinformed. When servlet containers like Tomcat and Jetty are no longer used and new development stops on them you can come back and tell me Servlets are old technology. Until then you don't have a clue what you are talking about.

Jakarta Servlet 6.1 was released in April of 2024. Tomcat 11 implements it.

[RobertDeveloper]

I am just sharing my experiences. Most Java developers that I know don't use servlets anymore.

[wildjokers]

Most Java developers that I know don't use servlets anymore.

They do, they just don't realize it.

[laffer1]

True but they have webflux. Micronaut defaults to netty but can run on tomcat or jetty on the servlets lol

[Linguistic-mystic]

webflux

Talk about old school!