//______________________________________________________________________________
//   |       |
//   | knipp |           Knipp Medien und Kommunikation GmbH
//    -------
//
//
//     Knipp RRI Toolkit
//
//
//     Copyright (C) 2005 by Knipp Medien und Kommunikation GmbH
//
//     This library is free software; you can redistribute it and/or
//     modify it under the terms of the GNU Lesser General Public License 
//     as published by the Free Software Foundation; either version 2.1 
//     of the License, or any later version.
// 
//     This library is distributed in the hope that it will be useful, 
//     but WITHOUT ANY WARRANTY; without even the implied warranty of
//     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
//     GNU Lesser General Public License for more details.
//
//     You should have received a copy of the GNU Lesser General
//     Public License along with this library; if not, write to the 
//     Free Software Foundation, Inc., 59 Temple Place, Suite 330, 
//     Boston, MA 02111-1307 USA 
//
//
//     initial author:    Klaus Malorny
//
//     version:           1.3 (15112), 2011/05/27 16:00:14
//                        $Revision: 14936 $ 
//                        $Date: 2010-11-05 15:57:40 +0100 (Fri, 05 Nov 2010) $
//                        $Author: Klaus.Malorny $
//

package de.knipp.rritoolkit;

import org.w3c.dom.Document;
import org.w3c.dom.DOMException;

import de.knipp.rritoolkit.request.Request;

import de.knipp.rritoolkit.response.Response;


/**
 *  interface to a class that is capabable of creating a suitable subclass
 *  of {@code DenicResponse} for the given response. The returned
 *  objects are initialized (i.e. the {@code fromXml} or
 *  {@code fromList} methods called). This is the responsibility of the
 *  caller. Implementations of this interface must be thread-safe.
 *
 *  @version  $Revision: 14936 $
 *  @author   Klaus Malorny
 */

public interface ResponseFactory
{
  /**
   *  create an instance based on the given XML document.  Since the
   *  content of the list is not necessarily self-describing in respect
   *  to the type of response, the request can be supplied to ease the
   *  selection of the correct subclass.
   *
   *  @param doc                      the document
   *  @param request                  the request, may be {@code null}
   *  @return                         the new instance
   *  @throws DOMException            on DOM exceptions
   *  @throws ResponseParseException  if the type could not be determined
   */

  public Response createResponse (Document doc, Request request)
    throws DOMException, ResponseParseException;
  
  
  /**
   *  create an instance based on the given key-value pair list. Since the
   *  content of the list is not necessarily self-describing in respect
   *  to the type of response, the request can be supplied to ease the
   *  selection of the correct subclass.
   *
   *  @param list                     the list
   *  @param request                  the request, may be {@code null}
   *  @return                         the created response
   *  @throws ResponseParseException  if the type could not be determined
   */
  
  public Response createResponse (KVMultiList list, Request request)
    throws ResponseParseException;
  
}