%%% BEGIN openflax/handler.erl %%%
%%%
%%% openflax - Open Source web server for Erlang/OTP
%%% Copyright (c)2003 Cat's Eye Technologies.  All rights reserved.
%%%
%%% Redistribution and use in source and binary forms, with or without
%%% modification, are permitted provided that the following conditions
%%% are met:
%%%
%%%   Redistributions of source code must retain the above copyright
%%%   notice, this list of conditions and the following disclaimer.
%%%
%%%   Redistributions in binary form must reproduce the above copyright
%%%   notice, this list of conditions and the following disclaimer in
%%%   the documentation and/or other materials provided with the
%%%   distribution.
%%%
%%%   Neither the name of Cat's Eye Technologies nor the names of its
%%%   contributors may be used to endorse or promote products derived
%%%   from this software without specific prior written permission.
%%%
%%% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
%%% CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
%%% INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
%%% MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
%%% DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
%%% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
%%% OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
%%% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
%%% OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
%%% ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
%%% OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
%%% OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
%%% POSSIBILITY OF SUCH DAMAGE. 

%% @doc Generic behaviour for OpenFlax handlers.
%%
%% <p>This module defines the interface that all OpenFlax handlers should
%% export, and any common functionality that they should share.</p>
%% 
%% @end

-module(openflax.handler).
-vsn('$Id: handler.erl 31 2004-04-23 07:00:11Z catseye $').
-author('catseye@catseye.mb.ca').
-copyright('Copyright (c)2003 Cat`s Eye Technologies. All rights reserved.').

-export([behaviour_info/1]).
-export([start_all/2]).

-import(lists).
-import(dict).

%% @spec behaviour_info(callbacks) -> [{function_name(), arity()}]
%%         function_name() = atom()
%%         arity() = integer()
%% @doc Yields a list of functions which must be exported by each handler
%% module that implements this behaviour.
%% <ul>
%% <li> <code>start(conf()) -> conf()</code> </li>
%% <p> This callback should initialize the handler and return a new
%% <code>conf()</code> if the initialization was successful;
%% otherwise, it should simply fail due to error.  The returned
%% <code>conf()</code> will be merged into the global configuration
%% section; therefore, it should be obtained from a call to
%% <code>openflax.conf:new/0</code> or <code>/1</code>, and
%% should <i>not</i> simply be a copy of the <code>conf()</code> which
%% was passed to <code>start/1</code>.</p>
%% <li> <code>stop(conf()) -> conf()</code> </li>
%% <p> This callback should shutdown all activity of the handler
%% and return the <code>conf()</code> it was given, perhaps with
%% modifications.</p>
%% <li> <code>serve(conf()) -> {response(), conf()}</code> </li>
%% <p> This callback should serve the resource implemented by the handler.
%% The handler may, of course, serve any number of different kinds of
%% resources, most likely based on the URL and/or the form arguments
%% of the request, which may be found in the <code>conf()</code> passed
%% to <code>serve/1</code>.  It should return a <code>response()</code>
%% as well as the <code>conf()</code> it was passed, perhaps with
%% modifications.</p>
%% </ul>

behaviour_info(callbacks) ->
  [
    {start, 1},
    {serve, 1},
    {stop, 1}
  ].

%% @spec start_all(conf(), master_dict()) -> conf()
%% @doc Starts all installed handler modules.
%% These handlers are listed in the <code>handler -> conf()</code>
%% dictionary passed to <code>start_all/1</code>, which typically is
%% drawn from the configuration files.

start_all(GlobalConf, MasterDict) ->
  start_all0(lists:sort(dict:to_list(MasterDict)), GlobalConf).

start_all0([], GlobalConf) ->
  GlobalConf;
start_all0([{Handler, HandlerConf} | Tail], GlobalConf) ->
  MergedConf = openflax.conf:merge(GlobalConf, HandlerConf),
  GlobalConf0 = case {Handler, catch Handler:start(MergedConf)} of
    {openflax, _} ->
      GlobalConf;
    {_, {'EXIT', {undef, _}}} ->
      GlobalConf;
    {_, HandlerConf0} ->
      openflax.conf:merge(GlobalConf, HandlerConf0)
    end,
  start_all0(Tail, GlobalConf0).

%%% END of openflax/handler.erl %%%