/*
CARNEGIE MELLON UNIVERSITY
NON-EXCLUSIVE END-USER
SOFTWARE LICENSE AGREEMENT
RETSINA(tm)
Reusable Environment for Task Structured Intelligent Network Agents(tm)
IMPORTANT: PLEASE READ THIS SOFTWARE LICENSE AGREEMENT ("AGREEMENT") CAREFULLY.
LICENSE
The CMU Software, together with any fonts accompanying this Agreement, whether
on disk, in read only memory or any other media or in any other form
(collectively, the "CMU Software") is never sold. It is non-exclusively
licensed by Carnegie Mellon University ("CMU") to you solely for your own
internal, non-commercial research purposes on the terms of this Agreement. CMU
retains the ownership of the CMU Software and any subsequent copies of the CMU
Software. The CMU Software and any copies made under this Agreement are subject
to this Agreement.
YOU MAY:
1. LOAD and USE the CMU Software as long as the CMU Software is only
used on one (1) computer by one (1) user at a time. This license does
not allow the CMU Software to exist on more than one (1) computer at
a time or on a computer network, including without limitation an
intranet network or a local area network.
2. USE the CMU Software solely for your own internal, non-commercial
research purposes.
3. COPY the CMU Software for back-up purposes only. You may make one
(1) copy of the CMU Software in machine-readable form for back-up
purposes. The back-up copy must contain all copyright notices
contained in the original CMU Software.
4. TERMINATE this Agreement by destroying the original and all copies
of the CMU Software in whatever form.
YOU MAY NOT:
1. Assign, delegate or otherwise transfer the CMU Software, the
license (including this Agreement), or any rights or obligations
hereunder or thereunder, to another person or entity. Any purported
assignment, delegation or transfer in violation of this provision
shall be void.
2. Loan, distribute, rent, lease, give, sublicense or otherwise
transfer the CMU Software (or any copy of the CMU Software), in whole
or in part, to any other person or entity.
3. Copy, alter, translate, decompile, disassemble, reverse engineer
or create derivative works from the CMU Software, including but not
limited to, modifying the CMU Software to make it operate on non-
compatible hardware.
4. Remove, alter or cause not to be displayed, any copyright notices
or startup messages contained in the CMU Software.
5. Export the CMU Software or the product components in violation of
any United States export laws.
Title to the CMU Software, including the ownership of all copyrights, patents,
trademarks and all other intellectual property rights subsisting in the
foregoing, and all adaptations to and modifications of the foregoing shall at
all times remain with CMU. CMU retains all rights not expressly licensed under
this Agreement. The CMU Software, including any images, graphics, photographs,
animation, video, audio, music and text incorporated therein is owned by CMU or
its suppliers and is protected by United States copyright laws and
international treaty provisions. Except as otherwise expressly provided in
this Agreement, the copying, reproduction, distribution or preparation of
derivative works of the CMU Software is strictly prohibited by such laws and
treaty provisions. Nothing in this Agreement constitutes a waiver of CMU's
rights under United States copyright law.
This Agreement and your rights are governed by the laws of the Commonwealth of
Pennsylvania. If for any reason a court of competent jurisdiction finds any
provision of this Agreement, or portion thereof, to be unenforceable, the
remainder of this Agreement shall continue in full force and effect.
THIS LICENSE SHALL TERMINATE AUTOMATICALLY if you fail to comply with the terms
of this Agreement.
DISCLAIMER OF WARRANTY ON CMU SOFTWARE
You expressly acknowledge and agree that your use of the CMU Software is at
your sole risk.
THE CMU SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, AND CMU
EXPRESSLY DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NON-INFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE RISK AS TO THE
QUALITY AND PERFORMANCE OF THE CMU SOFTWARE IS BORNE BY YOU. THIS DISCLAIMER
OF WARRANTIES, REMEDIES AND LIABILITY ARE FUNDAMENTAL ELEMENTS OF THE BASIS OF
THE AGREEMENT BETWEEN CMU AND YOU. CMU WOULD NOT BE ABLE TO PROVIDE THE CMU
SOFTWARE WITHOUT SUCH LIMITATIONS.
LIMITATION OF LIABILITY
THE CMU SOFTWARE IS BEING PROVIDED TO YOU FREE OF CHARGE. UNDER NO
CIRCUMSTANCES, INCLUDING NEGLIGENCE, SHALL CMU BE LIABLE UNDER ANY THEORY OR
FOR ANY DAMAGES INCLUDING, WITHOUT LIMITATION, DIRECT, INDIRECT, GENERAL,
SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY OR OTHER DAMAGES) ARISING OUT OF
THE USE OF OR INABILITY TO USE THE CMU SOFTWARE OR OTHERWISE RELATING TO THIS
AGREEMENT (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS,
BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION OR ANY OTHER PECUNIARY
LOSS), EVEN IF CMU HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME
JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR
CONSEQUENTIAL DAMAGES SO THIS LIMITATION MAY NOT APPLY TO YOU.
ADDITIONAL PROVISIONS YOU SHOULD BE AWARE OF
This Agreement constitutes the entire agreement between you and CMU regarding
the CMU Software and supersedes any prior representations, understandings and
agreements, either oral or written. No amendment to or modification of this
Agreement will be binding unless in writing and signed by CMU.
U.S. GOVERNMENT RESTRICTED RIGHTS
If the CMU Software or any accompanying documentation is used or acquired by or
on behalf of any unit, division or agency of the United States Government, this
provision applies. The CMU Software and any accompanying documentation is
provided with RESTRICTED RIGHTS. The use, modification, reproduction, release,
display, duplication or disclosure thereof by or on behalf of any unit,
division or agency of the Government is subject to the restrictions set forth
in subdivision (c)(1) of the Commercial Computer Software-Restricted Rights
clause at 48 CFR 52.227-19 and the restrictions set forth in the Rights in
Technical Data-Non-Commercial Items clause set forth in 48 CFR
252.227-7013. The contractor/manufacturer of the CMU Software and accompanying
documentation is Carnegie Mellon University, 5000 Forbes Avenue, Pittsburgh,
Pennsylvania 15213, U.S.A.
*/
/* Copyright (c) 1998, Dirk Kalp, Katia Sycara, RETSINA Project,
Carnegie Mellon University
All rights reserved
*/
/*----------------------------------------------------------------------------
HISTORY:
Spring/Summer 1998 Dirk Kalp (kalp@cs.cmu.edu)
Created the module.
Dec 03 1998 Dirk Kalp (kalp@cs.cmu.edu)
Added this HISTORY log.
----------------------------------------------------------------------------*/
package EDU.cmu.softagents.retsina.Communicator;
/** ConnectionDescriptors are provided only for Connections the agent
makes to servers (i.e., server agents), with the agent in the role
of the client. Descriptors are not needed for Connections this agent
has with clients since those Connections are passively created inside
the Communicator in response to explicit connection requests made by
the external clients.
*/
public class ConnectionDescriptor {
public static /*final*/ boolean DEBUG = true;
/*public*/ private Connection conn = null;
private String serverName = null;
private String clientName = null; // no longer true -> also just Communicator.agentName
private int localport = 0;
private static final int UNDEFINED_CONNECTION = 0;
private static final int SHARED_CONNECTION = 1;
private static final int EXCLUSIVE_CONNECTION = 2;
private static final int ACCEPTED_CONNECTION = 3; // needed?
private int usage = UNDEFINED_CONNECTION;
/** Added a layer of interface over this and changed method from public
to protected. It is now only available to the Communicator internally
and not to application modules. Need to update documentation to
reflect this and also the deemphasis on the explicit client/server
model presented in the code documentation. But we're in demo mode
again and I can't stop to do all that now, so later. -dirk 4/20/98
*/
/** For use by application modules outside the Communicator package
that want to send a msg to a server. A ConnectionDescriptor is
returned that represents a valid open Connection to the server
on which a client to server conversation can be carried out.
This Connection may also be shared by other client conversations
with the same server but each conversation would have its own
ConnectionDescriptor. Thus 2 Actions, each in a different top-level
task, using the same server would communicate with the server over
the same Connection but each would have different descriptors to refer
to the Connection. Each Action would eventually need to do a close()
on its descriptor when its conversation with the server concluded so
that the Connection itself could eventually be destroyed when no
longer in active use.
Returns the ConnectionDescriptor or null if a Connection cannot be
opened to the server or an invalid serverName is given.
*/
protected /*public*/ static ConnectionDescriptor openConnectionToServer(String serverName)
{
if ((serverName == null) || !hasNonWhiteSpace(serverName)) return null;
// See if we already have a shared Connection open to this server
// by looking it up in the special ConnectionTable for shared
// Connections to servers.
Connection sharedConn =
Communicator.sharedConnectionToServerTable.lookupConnection(serverName);
// As soon as a shared Connection goes bad, we take it
// out of this table but leave it in connectionTable
// until close_final() is done.
if (sharedConn != null) {
// We found an existing shared Connection so just bump
// its referenceCount.
sharedConn.open_again();
} else {
// No shared Connection so try to create one to this server.
sharedConn = Connection.newSharedConnectionToServer(serverName);
if (sharedConn == null) {
// print errmsg?
return null;
}
}
ConnectionDescriptor cd = new ConnectionDescriptor(sharedConn,
SHARED_CONNECTION);
sharedConn.associateDescriptor(cd);
return cd;
}
/** Added a layer of interface over this and changed method from public
to protected. It is now only available to the Communicator internally
and not to application modules. Need to update documentation to
reflect this and also the deemphasis on the explicit client/server
model presented in the code documentation. But we're in demo mode
again and I can't stop to do all that now, so later. -dirk 4/20/98
*/
/** For use by an application module outside the Communicator package
that wants to send a msg to a server using a Connection dedicated
to itself. A ConnectionDescriptor is returned that represents a valid
open Connection to the server on which a client to server conversation
can be carried out. This Connection is mapped to 1 ConnectionDescriptor
to provide exclusive use of the Connection to the owner of the
descriptor. It could be shared by other distinct conversations to this
server but only if the owner makes the descriptor available to others.
A close() on the descriptor should be done when use of the Connection
concludes.
Returns the ConnectionDescriptor or null if a Connection cannot be
opened to the server or an invalid serverName is given.
*/
protected /*public*/ static ConnectionDescriptor openExclusiveConnectionToServer(
String serverName)
{
if ((serverName == null) || !hasNonWhiteSpace(serverName)) return null;
Connection exclConn = Connection.newExclusiveConnectionToServer(serverName);
if (exclConn == null) {
// print errmsg?
return null;
}
ConnectionDescriptor cd = new ConnectionDescriptor(exclConn,
EXCLUSIVE_CONNECTION);
exclConn.associateDescriptor(cd);
return cd;
}
/** Hide the constructor so that creation of ConnectionDescriptors must
happen through the static methods openConnectionToServer() or
openExclusiveConnectionToServer().
*/
protected /*or private*/ ConnectionDescriptor(Connection conn, int usage)
{
this.conn = conn;
this.usage = usage;
serverName = conn.getServerName();
clientName = conn.getClientName();
localport = conn.getLocalport();
}
public String getServerName() {return serverName;}
public String getClientName() {return clientName;}
public int getLocalport() {return localport;}
public String getConnectionName() {return conn.getConnectionName();}
public boolean isConnectionAliveAndWell() {return conn.isAliveAndWell();}
protected Connection getConnection() {return conn;}
/** Added a layer of interface over this and changed method from public
to protected. It is now only available to the Communicator internally
and not to application modules. Need to update documentation to
reflect this and also the deemphasis on the explicit client/server
model presented in the code documentation. But we're in demo mode
again and I can't stop to do all that now, so later. -dirk 4/20/98
*/
/** This method allows a close on the ConnectionDescritor to occur
so that the corresponding Connection can be closed. The close on
the Connection may be a "soft" close if the Connection to the
server is being shared. This just decrements a reference count on
the Connection. If any msgs previously queued to the central
dispatch queue in the Communicator to be sent on this Connection
are still pending in the queue, the hard close of the Connection
will be delayed until those msgs get sent. But the descriptor close()
here will not block waiting for this to conclude.
*/
protected /*public*/ void close() {
if (usage == ACCEPTED_CONNECTION) return;
conn.close();
// Below not needed since conn.close() takes care of all this now.
/*********************************************************************
if (usage == EXCLUSIVE_CONNECTION) {
// Exclusive Connections get a hard close to delete the Connection.
conn.close_final();
} else {
// Shared Connections get a soft close to decrement their
// reference count. Connection won't be deleted until count
// is 0. At that time it should be deleted from both
// ConnectionTables in which it appears.
conn.close();
// Can we do the below in conn.close()?
// ANSWER: Yes I think so, just remember to do it and delete this below.
if (conn.referenceCount == 0)
Communicator.sharedConnectionToServerTable.deleteConnection(conn);
}
*********************************************************************/
}
// Checks is a string has any non-whitespace characters. Returns
// true if it does, false if it does not or if string is null.
//
private static boolean hasNonWhiteSpace(String str) {
if (str == null) return false;
char[] strChars = str.toCharArray();
for (int i=0; i<strChars.length; i++) {//replaced less-than sign w <
if ((strChars[i] != ' ') ||
(strChars[i] != '\t') ||
(strChars[i] != '\n'))
return true;
}
return false;
}
}