/*
* Copyright (c) 2001, 2003, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package org.jboss.com.sun.corba.se.pept.transport;
import org.jboss.com.sun.corba.se.pept.encoding.InputObject;
import org.jboss.com.sun.corba.se.pept.encoding.OutputObject;
import org.jboss.com.sun.corba.se.pept.protocol.MessageMediator;
/**
* <p>
* <code>Connection</code> represents a <em>transport</em> in the PEPt architecture.
* </p>
*
* @author Harold Carr
*/
public interface Connection
{
/**
* Used to determine if the <code>Connection</code> should register with the
* {@link org.jboss.com.sun.corba.se.pept.transport.TransportManager TransportManager}
* {@link org.jboss.com.sun.corba.se.pept.transport.Selector Selector} to handle read events.
*
* For example, an HTTP transport would not register since the requesting thread would just block on read when
* waiting for the reply.
*
* @return <code>true</code> if it should be registered.
*/
public boolean shouldRegisterReadEvent();
/**
* Used to determine if the <code>Connection</code> should register with the
* {@link org.jboss.com.sun.corba.se.pept.transport.TransportManager TransportManager}
* {@link org.jboss.com.sun.corba.se.pept.transport.Selector Selector} to handle read events.
*
* For example, an HTTP transport would not register since the requesting thread would just block on read when
* waiting for the reply.
*
* @return <code>true</code> if it should be registered.
*/
public boolean shouldRegisterServerReadEvent(); // REVISIT - why special?
/**
* Called to read incoming messages.
*
* @return <code>true</code> if the thread calling read can be released.
*/
public boolean read();
/**
* Close the <code>Connection</code>.
*
*/
public void close();
// REVISIT: replace next two with PlugInFactory (implemented by ContactInfo
// and Acceptor).
/**
* Get the {@link org.jboss.com.sun.corba.se.pept.transport.Acceptor Acceptor} that created this <code>Connection</code>.
*
* @return {@link org.jboss.com.sun.corba.se.pept.transport.Acceptor Acceptor}
*/
public Acceptor getAcceptor();
/**
* Get the {@link org.jboss.com.sun.corba.se.pept.transport.ContactInfo ContactInfo} that created this <code>Connection</code>
* .
*
* @return {@link org.jboss.com.sun.corba.se.pept.transport.ContactInfo ContactInfo}
*/
public ContactInfo getContactInfo();
/**
* Get the {@link org.jboss.com.sun.corba.se.pept.transport.EventHandler EventHandler} associated with this
* <code>Acceptor</code>.
*
* @return {@link org.jboss.com.sun.corba.se.pept.transport.EventHandler EventHandler}
*/
public EventHandler getEventHandler();
/**
* Indicates whether a {@link org.jboss.com.sun.corba.se.pept.transport.ContactInfo ContactInfo} or a
* {@link org.jboss.com.sun.corba.se.pept.transport.Acceptor Acceptor} created the <code>Connection</code>.
*
* @return <code>true</code> if <code>Connection</code> an {@link org.jboss.com.sun.corba.se.pept.transport.Acceptor Acceptor}
* created the <code>Connection</code>.
*/
public boolean isServer();
/**
* Indicates if the <code>Connection</code> is in the process of sending or receiving a message.
*
* @return <code>true</code> if the <code>Connection</code> is busy.
*/
public boolean isBusy();
/**
* Timestamps are used for connection management, in particular, for reclaiming idle <code>Connection</code>s.
*
* @return the "time" the <code>Connection</code> was last used.
*/
public long getTimeStamp();
/**
* Timestamps are used for connection management, in particular, for reclaiming idle <code>Connection</code>s.
*
* @param time
* - the "time" the <code>Connection</code> was last used.
*/
public void setTimeStamp(long time);
/**
* The "state" of the <code>Connection</code>.
*
* param state
*/
public void setState(String state);
/**
* Grab a write lock on the <code>Connection</code>.
*
* If another thread already has a write lock then the calling thread will block until the lock is released. The
* calling thread must call {@link #writeUnlock} when it is done.
*/
public void writeLock();
/**
* Release a write lock on the <code>Connection</code>.
*/
public void writeUnlock();
/*
* Send the data encoded in {@link org.jboss.com.sun.corba.se.pept.encoding.OutputObject OutputObject} on the
* <code>Connection</code>.
*
* @param outputObject
*/
public void sendWithoutLock(OutputObject outputObject);
/**
* Register an invocation's {@link org.jboss.com.sun.corba.se.pept.protocol.MessageMediator MessageMediator} with the
* <code>Connection</code>.
*
* This is useful in protocols which support fragmentation.
*
* @param messageMediator
*/
public void registerWaiter(MessageMediator messageMediator);
/**
* If a message expect's a response then this method is called.
*
* This method might block on a read (e.g., HTTP), put the calling thread to sleep while another thread read's the
* response (e.g., GIOP), or it may use the calling thread to perform the server-side work (e.g., Solaris Doors).
*
* @param messageMediator
*/
public InputObject waitForResponse(MessageMediator messageMediator);
/**
* Unregister an invocation's {@link org.jboss.com.sun.corba.se.pept.protocol.MessageMediator MessageMediator} with the
* <code>Connection</code>.
*
* @param messageMediator
*/
public void unregisterWaiter(MessageMediator messageMediator);
public void setConnectionCache(ConnectionCache connectionCache);
public ConnectionCache getConnectionCache();
}
// End of file.