libservlet

# Servlet API Conversion Details

- Naming Conventions
- Method Signatures
- Return Values
- Interfaces
- Exception Handling
- Event Handling
- I/O
- Locales
- Character Encodings and Conversions
- Threads

## Naming Conventions

Variable and method names use the fooBar capitalization style per the Java (TM) Servlet API specification.

## Method Signatures

Java (TM) allow multiple signatures for each method, while Perl only allows one. Luckily, the Java (TM) API specifies few methods with multiple signatures, and those that do exist are easy to collapse into one method simply by allowing parameters to be optional and/or undef values. It turns out to be a non-issue.

## Return Values

Return values are mapped from Java (TM) to the Perl API as such:

string, integer, etc.
  These values are simple scalars, or undef.

boolean
  These values are either 1 or undef.

arrays, enumerations
  In list context, these values are arrays (possibly empty). In scalar context, the values are array references.

maps
  In list context, these values are hashes (possibly empty). In scalar context, the values are hash references.

## Interfaces

The Java (TM) version of the Servlet API is mostly comprised of interfaces. They cannot be instantiated directly but rather must be implemented by classes. Their function is to specify attributes and methods that must be provided by the implementation classes. Perl has no equivalent builtin mechanism, so we simply provide a package for the interface (to enable `isa()` type checking) and leave it to servlet container developers to provide implementations.

## Exception Handling

The API uses Exception::Class for exceptions. It uses `die()` to throw them and `eval()` to catch them. Servlet::Util::Exception inherits from Exception::Class::Base and is itself the base class for all exceptions used by the Servlet API, whether part of the API specification or provided as utilities.

## Event Handling

The API provides Servlet::Util::Event as a base class for event objects.

## I/O

It's very tempting to make the Servlet::ServletInputStream and Servlet::ServletOutputStream interfaces extend IO::Handle. However, this would restrict the choice of implementations, and it would make methods available that the servlet container might wish to restrict. By making them interfaces, the servlet container developer can choose to extend IO::Handle, to delegate to an instance of that class, or any other mechanism.

## Locales

## Character Encodings and Conversions

## Threads