doc/bundles/org.eclipse.ecf.doc/html/concepts/intro.html - ecf/org.eclipse.ecf - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2007. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
 <meta http-equiv="Content-Language" content="en-us">
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1"
 	type="text/css">
 <style type="text/css">
 td {border-top: solid thin black;}
 img[alt] {background-color:#ffdddd;}
 tr {vertical-align: top;}
 </style>
 <script language="JavaScript" type="text/javascript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script>
 </head>
 <body>
 <h1><img src="../../intro/css/images/ecf_intro.gif">Eclipse Communication Framework (ECF)</h1>
 <p>
 	<h2>ECF Containers</h2>
        ECF introduces the concept of a communications <b>container</b>.  ECF containers represent access to
        a protocol-specific communications context. For connection-oriented communications, an ECF container loosely
        corresponds to the traditional notion of a communications <b>session</b>, but the more general container concept is also
        useful for capturing context even if the communications are non connection-oriented.
        <p></p>
        ECF containers can represent both point-to-point communications (e.g. client/server) or
        publish-and-subscribe (group) communications.  Container instances can provide access to synchronous
        communications only, asynchronous communications only, or both together.  This flexibility allows
        many communications applications to be constructed out of one or more containers...each of which
        provides access to some specific communications context and some protocol for communicating within
        that context.
        <h2><a name="Instance Creation"></a>Instance Creation</h2>
        Container instance creation is done via ECF-provided factory APIs.  For example, here's code to create
        and IContainer instance:
        <pre>
        IContainer container = ContainerFactory.getDefault().createContainer("containertype");
        </pre>
        Once constructed, <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/IContainer.html">IContainer</a> instances may be used in the manner appropriate for the given application.  When
        no longer required the <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/IContainer.html#dispose()">IContainer.dispose()</a> method should be called to release any resources associated with
        the container instance upon construction.
        <h2><a name="Container Connection"></a>Container Connection/Disconnection</h2>
        The IContainer interface exposes two key methods:  <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/IContainer.html#connect(org.eclipse.ecf.core.identity.ID,%20org.eclipse.ecf.core.security.IConnectContext)">connect(ID targetID, IConnectContect connectContext)</a> and disconnect().
        As is obvious, these two methods allow
        container implementations to initiate communication with remote services,
        either server-based or group-based communications.
        <p></p>
        Notice the first parameter to the connect method...<b>targetID</b>.  TargetID is of
        type <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/identity/ID.html">ID</a>.  The <b>targetID</b> parameter
        <b>identifies the target server or group</b> for the connect operation.  It is of type <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/identity/ID.html">ID</a> so that the
        to allow the target communications service to be of many kinds...e.g. client-server or peer-to-peer.  For example, for http communication the targetID would consist of
        the URL specifying a particular file at a particular path on a particular server...e.g: <b>http://www.eclipse.org/ecf</b>.  For some
        other communications protocol the ID provided would be different...e.g:  <b>sip:someone@example.com;transport=tcp</b>.  All such targets for
        connect may be represented via an instance of the ID interface.
        <h2><a name="Example Connection Code"></a>Example Container Creation and Connection Code</h2>
        Here's an example code snippet that shows the creation and connection of an ECF container:
        <pre>
        // make container instance
        IContainer cont = ContainerFactory.getDefault().createContainer("ecf.generic.client");
        // make targetID
        ID targetID = IDFactory.getDefault().createID(cont.getConnectNamespace(),"ecftcp://ecf1.osuosl.org:3282/server");
        // then connect to targetID
        cont.connect(targetID,null);
        </pre>
        <h2><a name="Extensibility"></a>Container Extensibility through Adapters</h2>
        In order to support run-time extensibility, the IContainer interface inherits from org.eclipse.core.runtime.IAdaptable.  This
        interface exposes the 'getAdapter(Class intf)' method.  In the case of IContainer instances,
        this allows clients to query the container at runtime about it's exposed interfaces, and get
        access to those interfaces if available.  So, for example, perhaps we're interested in creating an
        instant messaging application and wish to use the capabilities exposed by the
        <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/presence/IPresenceContainer.html">IPresenceContainer</a> interface.
        To do this, we simply query the IContainer instance at runtime to see if it provides access
        to IPresenceContainer capabilities:
        <pre>
        IPresenceContainer pc = (IPresenceContainer) cont.getAdapter(IPresenceContainer.class);
        if (pc != null) {
            // The container DOES expose IPresenceContainer capabilities, so we can use them!
        } else {
            // The container does NOT expose IPresenceContainer capabilities...we're out of luck
        }
        </pre>
        Among other positive characteristics, this adapter mechanism provides a consistent-yet-simple way for
        a wide variety of container types to be defined and used without the need to update the ECF
        IContainer abstractions.
        <p></p>
        UNDER CONSTRUCTION - 9/9/05
        <p></p>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>
	<head>
	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2007. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
	<meta http-equiv="Content-Language" content="en-us">
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1"
	type="text/css">
	<style type="text/css">
	td {border-top: solid thin black;}
	img[alt] {background-color:#ffdddd;}
	tr {vertical-align: top;}
	</style>
	<script language="JavaScript" type="text/javascript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script>
	</head>
	<body>
	<h1><img src="../../intro/css/images/ecf_intro.gif">Eclipse Communication Framework (ECF)</h1>
	<p>
	<h2>ECF Containers</h2>
	ECF introduces the concept of a communications <b>container</b>. ECF containers represent access to
	a protocol-specific communications context. For connection-oriented communications, an ECF container loosely
	corresponds to the traditional notion of a communications <b>session</b>, but the more general container concept is also
	useful for capturing context even if the communications are non connection-oriented.
	<p></p>
	ECF containers can represent both point-to-point communications (e.g. client/server) or
	publish-and-subscribe (group) communications. Container instances can provide access to synchronous
	communications only, asynchronous communications only, or both together. This flexibility allows
	many communications applications to be constructed out of one or more containers...each of which
	provides access to some specific communications context and some protocol for communicating within
	that context.
	<h2><a name="Instance Creation"></a>Instance Creation</h2>
	Container instance creation is done via ECF-provided factory APIs. For example, here's code to create
	and IContainer instance:
	<pre>
	IContainer container = ContainerFactory.getDefault().createContainer("containertype");
	</pre>
	Once constructed, <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/IContainer.html">IContainer</a> instances may be used in the manner appropriate for the given application. When
	no longer required the <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/IContainer.html#dispose()">IContainer.dispose()</a> method should be called to release any resources associated with
	the container instance upon construction.
	<h2><a name="Container Connection"></a>Container Connection/Disconnection</h2>
	The IContainer interface exposes two key methods: <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/IContainer.html#connect(org.eclipse.ecf.core.identity.ID,%20org.eclipse.ecf.core.security.IConnectContext)">connect(ID targetID, IConnectContect connectContext)</a> and disconnect().
	As is obvious, these two methods allow
	container implementations to initiate communication with remote services,
	either server-based or group-based communications.
	<p></p>
	Notice the first parameter to the connect method...<b>targetID</b>. TargetID is of
	type <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/identity/ID.html">ID</a>. The <b>targetID</b> parameter
	<b>identifies the target server or group</b> for the connect operation. It is of type <a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/identity/ID.html">ID</a> so that the
	to allow the target communications service to be of many kinds...e.g. client-server or peer-to-peer. For example, for http communication the targetID would consist of
	the URL specifying a particular file at a particular path on a particular server...e.g: <b>http://www.eclipse.org/ecf</b>. For some
	other communications protocol the ID provided would be different...e.g: <b>sip:someone@example.com;transport=tcp</b>. All such targets for
	connect may be represented via an instance of the ID interface.
	<h2><a name="Example Connection Code"></a>Example Container Creation and Connection Code</h2>
	Here's an example code snippet that shows the creation and connection of an ECF container:
	<pre>
	// make container instance
	IContainer cont = ContainerFactory.getDefault().createContainer("ecf.generic.client");
	// make targetID
	ID targetID = IDFactory.getDefault().createID(cont.getConnectNamespace(),"ecftcp://ecf1.osuosl.org:3282/server");
	// then connect to targetID
	cont.connect(targetID,null);
	</pre>
	<h2><a name="Extensibility"></a>Container Extensibility through Adapters</h2>
	In order to support run-time extensibility, the IContainer interface inherits from org.eclipse.core.runtime.IAdaptable. This
	interface exposes the 'getAdapter(Class intf)' method. In the case of IContainer instances,
	this allows clients to query the container at runtime about it's exposed interfaces, and get
	access to those interfaces if available. So, for example, perhaps we're interested in creating an
	instant messaging application and wish to use the capabilities exposed by the
	<a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/presence/IPresenceContainer.html">IPresenceContainer</a> interface.
	To do this, we simply query the IContainer instance at runtime to see if it provides access
	to IPresenceContainer capabilities:
	<pre>
	IPresenceContainer pc = (IPresenceContainer) cont.getAdapter(IPresenceContainer.class);
	if (pc != null) {
	// The container DOES expose IPresenceContainer capabilities, so we can use them!
	} else {
	// The container does NOT expose IPresenceContainer capabilities...we're out of luck
	}
	</pre>
	Among other positive characteristics, this adapter mechanism provides a consistent-yet-simple way for
	a wide variety of container types to be defined and used without the need to update the ECF
	IContainer abstractions.
	<p></p>
	UNDER CONSTRUCTION - 9/9/05
	<p></p>
	</body>
	</html>