content: /*
   * Copyright (c) 2008-2009, Motorola, Inc.
   *
   * 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 the Motorola, Inc. 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 COPYRIGHT HOLDER 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.
   */
  
  package javax.obex;
  
  import java.io.IOException;
  
  /**
   * The <code>SessionNotifier</code> interface defines a connection notifier for
   * server-side OBEX connections. When a <code>SessionNotifier</code> is created
   * and calls <code>acceptAndOpen()</code>, it will begin listening for clients
   * to create a connection at the transport layer. When the transport layer
   * connection is received, the <code>acceptAndOpen()</code> method will return a
   * <code>javax.microedition.io.Connection</code> that is the connection to the
   * client. The <code>acceptAndOpen()</code> method also takes a
   * <code>ServerRequestHandler</code> argument that will process the requests
   * from the client that connects to the server.
   * @hide
   */
  public interface SessionNotifier {
  
      /**
       * Waits for a transport layer connection to be established and specifies
       * the handler to handle the requests from the client. No authenticator is
       * associated with this connection, therefore, it is implementation
       * dependent as to how an authentication challenge and authentication
       * response header will be received and processed.
       * <P>
       * <H4>Additional Note for OBEX over Bluetooth</H4> If this method is called
       * on a <code>SessionNotifier</code> object that does not have a
       * <code>ServiceRecord</code> in the SDDB, the <code>ServiceRecord</code>
       * for this object will be added to the SDDB. This method requests the BCC
       * to put the local device in connectable mode so that it will respond to
       * connection attempts by clients.
       * <P>
       * The following checks are done to verify that the service record provided
       * is valid. If any of these checks fail, then a
       * <code>ServiceRegistrationException</code> is thrown.
       * <UL>
       * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service
       * attributes for a <code>btgoep</code> service record, must be present in
       * the <code>ServiceRecord</code> associated with this notifier.
       * <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList
       * <LI>The <code>ServiceRecord</code> associated with this notifier must not
       * have changed the RFCOMM server channel number
       * </UL>
       * <P>
       * This method will not ensure that <code>ServiceRecord</code> associated
       * with this notifier is a completely valid service record. It is the
       * responsibility of the application to ensure that the service record
       * follows all of the applicable syntactic and semantic rules for service
       * record correctness.
       * @param handler the request handler that will respond to OBEX requests
       * @return the connection to the client
       * @throws IOException if an error occurs in the transport layer
       * @throws NullPointerException if <code>handler</code> is <code>null</code>
       */
      ObexSession acceptAndOpen(ServerRequestHandler handler) throws IOException;
  
      /**
       * Waits for a transport layer connection to be established and specifies
       * the handler to handle the requests from the client and the
       * <code>Authenticator</code> to use to respond to authentication challenge
       * and authentication response headers.
       * <P>
       * <H4>Additional Note for OBEX over Bluetooth</H4> If this method is called
       * on a <code>SessionNotifier</code> object that does not have a
       * <code>ServiceRecord</code> in the SDDB, the <code>ServiceRecord</code>
       * for this object will be added to the SDDB. This method requests the BCC
       * to put the local device in connectable mode so that it will respond to
       * connection attempts by clients.
       * <P>
       * The following checks are done to verify that the service record provided
       * is valid. If any of these checks fail, then a
       * <code>ServiceRegistrationException</code> is thrown.
       * <UL>
       * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service
       * attributes for a <code>btgoep</code> service record, must be present in
       * the <code>ServiceRecord</code> associated with this notifier.
       * <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList
       * <LI>The <code>ServiceRecord</code> associated with this notifier must not
       * have changed the RFCOMM server channel number
       * </UL>
       * <P>
       * This method will not ensure that <code>ServiceRecord</code> associated
       * with this notifier is a completely valid service record. It is the
       * responsibility of the application to ensure that the service record
       * follows all of the applicable syntactic and semantic rules for service
       * record correctness.
       * @param handler the request handler that will respond to OBEX requests
       * @param auth the <code>Authenticator</code> to use with this connection;
       *        if <code>null</code> then no <code>Authenticator</code> will be
       *        used
       * @return the connection to the client
       * @throws IOException if an error occurs in the transport layer
       * @throws NullPointerException if <code>handler</code> is <code>null</code>
       */
      ObexSession acceptAndOpen(ServerRequestHandler handler, Authenticator auth) throws IOException;
  }
  