1 /*
   2  * Copyright (c) 2001, 2003, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.corba.se.pept.transport;
  27 
  28 import java.io.IOException;
  29 
  30 import com.sun.corba.se.pept.encoding.InputObject;
  31 import com.sun.corba.se.pept.encoding.OutputObject;
  32 import com.sun.corba.se.pept.protocol.MessageMediator;
  33 import com.sun.corba.se.pept.transport.EventHandler;
  34 
  35 
  36 /**
  37  * <p><code>Connection</code> represents a <em>transport</em> in the
  38  * PEPt architecture.</p>
  39  *
  40  * @author Harold Carr
  41 */
  42 public interface Connection
  43 {
  44     /**
  45      * Used to determine if the <code>Connection</code> should register
  46      * with the
  47      * {@link com.sun.corba.se.pept.transport.TransportManager
  48      * TransportManager}
  49      * {@link com.sun.corba.se.pept.transport.Selector Selector}
  50      * to handle read events.
  51      *
  52      * For example, an HTTP transport would not register since the requesting
  53      * thread would just block on read when waiting for the reply.
  54      *
  55      * @return <code>true</code> if it should be registered.
  56      */
  57     public boolean shouldRegisterReadEvent();
  58 
  59     /**
  60      * Used to determine if the <code>Connection</code> should register
  61      * with the
  62      * {@link com.sun.corba.se.pept.transport.TransportManager
  63      * TransportManager}
  64      * {@link com.sun.corba.se.pept.transport.Selector Selector}
  65      * to handle read events.
  66      *
  67      * For example, an HTTP transport would not register since the requesting
  68      * thread would just block on read when waiting for the reply.
  69      *
  70      * @return <code>true</code> if it should be registered.
  71      */
  72     public boolean shouldRegisterServerReadEvent(); // REVISIT - why special?
  73 
  74     /**
  75      * Called to read incoming messages.
  76      *
  77      * @return <code>true</code> if the thread calling read can be released.
  78      */
  79     public boolean read();
  80 
  81     /**
  82      * Close the <code>Connection</code>.
  83      *
  84      */
  85     public void close();
  86 
  87     // REVISIT: replace next two with PlugInFactory (implemented by ContactInfo
  88     // and Acceptor).
  89 
  90     /**
  91      * Get the
  92      * {@link com.sun.corba.se.pept.transport.Acceptor Acceptor}
  93      * that created this <code>Connection</code>.
  94      *
  95      * @return
  96      * {@link com.sun.corba.se.pept.transport.Acceptor Acceptor}
  97      */
  98     public Acceptor getAcceptor();
  99 
 100     /**
 101      * Get the
 102      * {@link com.sun.corba.se.pept.transport.ContactInfo ContactInfo}
 103      * that created this <code>Connection</code>.
 104      *
 105      * @return
 106      * {@link com.sun.corba.se.pept.transport.ContactInfo ContactInfo}
 107      */
 108     public ContactInfo getContactInfo();
 109 
 110     /**
 111      * Get the
 112      * {@link com.sun.corba.se.pept.transport.EventHandler EventHandler}
 113      * associated with this <code>Acceptor</code>.
 114      *
 115      * @return
 116      * {@link com.sun.corba.se.pept.transport.EventHandler EventHandler}
 117      */
 118     public EventHandler getEventHandler();
 119 
 120     /**
 121      * Indicates whether a
 122      * {@link com.sun.corba.se.pept.transport.ContactInfo ContactInfo}
 123      * or a
 124      * {@link com.sun.corba.se.pept.transport.Acceptor Acceptor}
 125      * created the
 126      * <code>Connection</code>.
 127      *
 128      * @return <code>true</code> if <code>Connection</code> an
 129      * {@link com.sun.corba.se.pept.transport.Acceptor Acceptor}
 130      * created the <code>Connection</code>.
 131      */
 132     public boolean isServer();
 133 
 134     /**
 135      * Indicates if the <code>Connection</code> is in the process of
 136      * sending or receiving a message.
 137      *
 138      * @return <code>true</code> if the <code>Connection</code> is busy.
 139      */
 140     public boolean isBusy();
 141 
 142     /**
 143      * Timestamps are used for connection management, in particular, for
 144      * reclaiming idle <code>Connection</code>s.
 145      *
 146      * @return the "time" the <code>Connection</code> was last used.
 147      */
 148     public long getTimeStamp();
 149 
 150     /**
 151      * Timestamps are used for connection management, in particular, for
 152      * reclaiming idle <code>Connection</code>s.
 153      *
 154      * @param time - the "time" the <code>Connection</code> was last used.
 155      */
 156     public void setTimeStamp(long time);
 157 
 158     /**
 159      * The "state" of the <code>Connection</code>.
 160      *
 161      * param state
 162      */
 163     public void setState(String state);
 164 
 165     /**
 166      * Grab a write lock on the <code>Connection</code>.
 167      *
 168      * If another thread already has a write lock then the calling
 169      * thread will block until the lock is released.  The calling
 170      * thread must call
 171      * {@link #writeUnlock}
 172      * when it is done.
 173      */
 174     public void writeLock();
 175 
 176     /**
 177      * Release a write lock on the <code>Connection</code>.
 178      */
 179     public void writeUnlock();
 180 
 181     /*
 182      * Send the data encoded in
 183      * {@link com.sun.corba.se.pept.encoding.OutputObject OutputObject}
 184      * on the <code>Connection</code>.
 185      *
 186      * @param outputObject
 187      */
 188     public void sendWithoutLock(OutputObject outputObject);
 189 
 190     /**
 191      * Register an invocation's
 192      * {@link com.sun.corba.se.pept.protocol.MessageMediator MessageMediator}
 193      * with the <code>Connection</code>.
 194      *
 195      * This is useful in protocols which support fragmentation.
 196      *
 197      * @param messageMediator
 198      */
 199     public void registerWaiter(MessageMediator messageMediator);
 200 
 201     /**
 202      * If a message expect's a response then this method is called.
 203      *
 204      * This method might block on a read (e.g., HTTP), put the calling
 205      * thread to sleep while another thread read's the response (e.g., GIOP),
 206      * or it may use the calling thread to perform the server-side work
 207      * (e.g., Solaris Doors).
 208      *
 209      * @param messageMediator
 210      */
 211     public InputObject waitForResponse(MessageMediator messageMediator);
 212 
 213     /**
 214      * Unregister an invocation's
 215      * {@link com.sun.corba.se.pept.protocol.MessageMediator MessageMediator}
 216      * with the <code>Connection</code>.
 217      *
 218      * @param messageMediator
 219      */
 220     public void unregisterWaiter(MessageMediator messageMediator);
 221 
 222     public void setConnectionCache(ConnectionCache connectionCache);
 223 
 224     public ConnectionCache getConnectionCache();
 225 }
 226 
 227 // End of file.