Naming convention for different types of Filters

[Joe Walnes]

I need a break from reviewing logos. Back to the never ending config
stuff...

Because we want to give users the choice of how to configure SiteMesh
(e.g. programatically, via XML, <init-params>, Spring,
convention....), WITHOUT making it too confusing or adding too many
layers of indirection/factories/providers, I've ended up with a
different set of top-level Servlet Filters.

But I'm struggling to come up with sane names for the filters.

What I have at the moment:
org.sitemesh.config.xml.XmlConfiguredSiteMeshFilter
org.sitemesh.config.properties.InitParamConfiguredSiteMeshFilter
org.sitemesh.config.spring.SpringConfiguredSiteMeshFilter
...etc...

Looks a bit scary. Any suggestions for how to simplify the names, yet
have them meaningful?

-Joe

[Patrick Lightbody]

No big ideas here, but I'd say keep the "default" one named simple...
like just SiteMeshFilter.

Patrick

[Joe Walnes]

Which leads on to the question... what should be the default config mechanism?

[Patrick Lightbody]

The one that requires no config? Does such a thing exist? :)

[Hani Suleiman]

Why not just let the package name decide? So call them all
SiteMeshFilter, in different packages? Or too confusing?

[Richard L. Burton III]

 I think that maybe too error prone for the developers. My thought on that is most developers have gotten use to intellisense and look mostly at the top level package name and the class to determine if they selected the right class.

I would lean towards naming the classes according to the provider type.

e.g.,

SpringFilterConfigurator
SpringOfflineConfigurator

I'm not sure if SiteMesh needs to be repeated in the class name personally.

The default Configurator I believe should leverage sensible defaults that can be changed. I guess then the next question is how? Since there's a web based configurator and offline version.

--
-Richard L. Burton III

[Mathias Bogaert]

How about having one com.sitemesh.config.SiteMeshFilter and inner classes such as SpringConfigStrategy, InitParamConfigStrategy, XmlConfigStrategy.

[Joe Walnes]

The requirements are (in order of importance):

  1. Make it really really simple for users to get started with SM - installing it in their web-app.

  2. Allow the user to select a config mechanism that best suites their application.

  3. Allow advanced users of framework integrators to implement new config mechanisms (e.g. Grails, NanoContainer).

I've been weighing up 2 fundamental approaches to do this:

1. Different Filter implementation per config mechanism

Examples:

<filter>
  <filter-class>org.sitemesh.config.properties.InitParamConfiguredSiteMeshFilter</filter-class>
  <init-param>
    <param-name>decoratorMappings</param-name>
    <param-value>/*=/decorators/main.html</param-name>
  </int-param>
</filter>

<filter>
  <filter-class>org.sitemesh.config.xml.XmlConfiguredSiteMeshFilter</filter-class>
  <!-- Supplemented by sitemesh.xml -->
</filter>

<filter>
  <filter-class>org.sitemesh.config.spring.SpringConfiguredSiteMeshFilter</filter-class>
  <!-- Supplemented by Spring beans.xml -->
</filter>

New config mechanism can be introduced by subclassing SiteMeshFilter.

2. Single Filter implementation with pluggable config provider

Examples:

<filter>
  <filter-class>org.sitemesh.config.SiteMeshFilter</filter-class>
  <init-param>
    <param-name>configType</param-name>
    <param-value>org.sitemesh.config.properties.PropertiesConfigurator</param-name>
  </int-param>
  <init-param>
    <param-name>decoratorMappings</param-name>
    <param-value>/*=/decorators/main.html</param-name>
  </int-param>
</filter>

<filter>
  <filter-class>org.sitemesh.config.SiteMeshFilter</filter-class>
  <init-param>
    <param-name>configType</param-name>
    <param-value>org.sitemesh.config.xml.XmlConfigurator</param-name>
  </int-param>
  <!-- Supplemented by sitemesh.xml -->
</filter>

<filter>
  <filter-class>org.sitemesh.config.SiteMeshFilter</filter-class>
  <init-param>
    <param-name>configType</param-name>
    <param-value>org.sitemesh.config.spring.SpringConfigurator</param-name>
  </int-param>
  <!-- Supplemented by Spring beans.xml -->
</filter>

New config mechanisms can be introduce by implementing a Configurator interface and passing the class name as the configType init param.

---

From an implementation point of view, I was leaning towards option 2 - but as soon I started writing the end user documentation, I saw that it added unnecessary complication to the end user. I now prefer option 1 because it's more minimal in web.xml and does not require the users to learn a new concept (the Configurator).

Which brings me back to the question... what should we name those classes to be used in web.xml?

[Hani Suleiman]

Why do you need the 'Configured' part in the class name? Are there non-
configured ones?

So perhaps InitParamSitemeshFilter, XmlSiteMeshFilter, and
SpringSiteMeshFilter?

Another option is having a SiteMeshFilter that auto-discovers its
configuration (or even allows it to come from whatever is specified).
So it could combine init params, check for sitemesh.xml, and find a
spring context and use that if its around, and degrate gracefully
whenever any piece is missing. A log.info explaining what it actually
found would go a long way towards resolving any user mistakes/
confusion (I know you're against logging joe, but I think it'd be
useful on startup if you choose to go down the auto-discovery/config
route).

[Joe Walnes]

Yeah, could drop the 'Configured' part. I guess I wanted to be explicit (because XmlSiteMeshFilter could suggest that SiteMesh had something to do with XML processing).

The auto-discovery option could work. Need to be careful as it could lead down a path of hidden-magic that could end up getting users confused, even with logging.

Having thought about it a bit more... it might be worth merging the init-param and XML config into the same mechanism, and making that the default 'SiteMeshFilter'. It would allow config to be loaded from params, XML, or both.

  <filter>

    <filter-class>org.sitemesh.config.SiteMeshFilter</filter-class>

    <init-param>

      .. some param ..

    </init-param>

    <init-param>

      <!-- optional: load additional config from here -->

      <param-name>config</param-name>

      <param-value>/WEB-INF/sitemesh.xml</param-name>

    </init-param>

  </filter>

This is growing on me because:

* Most users will be fine just using this one Filter

* Users who like XML are happy - they do it all in the XML file.

* Users who hate additional config files are happy - they just do it all inline.

* It's possible to separate different aspects of config (e.g. all class names in init-params, and mappings in XML).

* It hides proliferation of classes that the user shouldn't care about.

For the other stuff like Spring integration, it would be fine to have additional classes like SpringSiteMeshFilter.

I think that could work.

-j