Skip to main content
Jump to: navigation, search

Difference between revisions of "ECF API Refactoring"

(API Refactorings)
 
(30 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Prior to 1.0, ECF will be going through a concerted API and exemplary app refactoring effort. See below for list of desired refactorings and current state
+
Prior to 1.0, ECF will be going through a concerted API and exemplary applications refactoring and restructuring effort.
  
==API Refactorings==
+
==Items In Progress==
  
===Split org.eclipse.ecf Core Plugin into 2 or 3 Plugins--LARGE===
+
===Add Bulletin Board API to ECF Plugins and Features (Major)===
 +
Add Bulletin Board API. Remove EE 1.5 dependencies.
 +
 
 +
See: Bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=150756 #150756]
 +
 
 +
===API Review===
 +
An overwhelming number of classes in ECF at the moment are not being marked as internal packages. Whilst this may be the actual intent of the plug-ins, many of these non-internal classes are completely undocumented but are generated along with the published javadocs on the ECF website.
 +
 
 +
For this review, ECF code needs to clearly mark provisional APIs as being provisional, interfaces that should not be implemented by clients should have that stated clearly in the class level documentation, classes needs to be moved to internal packages (such as Trace, classes extending Plugin or AbstractUIPlugin, any others that are found during this review etc.), everything that has been approved as being public API needs to be marked with @since 1.0 when ECF 1.0 is released, and many others.
 +
 
 +
See [[API Central]] for further information Eclipse conventions and best practices for API development.
 +
 
 +
==Completed Items==
 +
 
 +
===Streamline ClientSOContainer===
 +
Streamline handling of creating/passing in connect data for new kind of authentication.
 +
 +
See: Bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=150398 #150398]
 +
 
 +
===Create filetransfer plugin, remove fileshare plugin===
 +
 
 +
Remove org.eclipse.ecf.fileshare API packages and classes.
 +
 
 +
Create a new plugin: org.eclipse.ecf.filetransfer.
 +
 
 +
'''Status''':  Started by SBL
 +
 
 +
===Split org.eclipse.ecf Core Plugin into 2 or 3 Plugins (Major)===
 
Refactor org.eclipse.ecf plugin into 2 or 3 plugins.  This is a large refactoring effort.
 
Refactor org.eclipse.ecf plugin into 2 or 3 plugins.  This is a large refactoring effort.
 
See discussion thread on mailing list: http://dev.eclipse.org/mhonarc/lists/ecf-dev/msg00399.html
 
See discussion thread on mailing list: http://dev.eclipse.org/mhonarc/lists/ecf-dev/msg00399.html
  
'''Status''': Not Done
+
1) The 'core plugin' (id: org.eclipse.ecf: 130K) is now been split into three plugins:
===Add Bulletin Board API to ECF Plugins and Features--LARGE===
+
Add Bulletin Board API. Remove EE 1.5 dependencies
+
See: https://bugs.eclipse.org/bugs/show_bug.cgi?id=150756
+
  
'''Status''': Not Done
+
a) org.eclipse.ecf.identity (31K)
 +
b) org.eclipse.ecf (49K)
 +
c) org.eclipse.ecf.sharedobject (66K)
  
===Create filetransfer plugin, remove fileshare plugin===
+
Now, b depends upon a, and c depends upon b.
 +
 
 +
All of the other API plugins (presence [23K], datashare, fileshare, discovery [10K]) now depend on *b* (and a) but *not* c.
 +
 
 +
2) Many classes and packages have changed and moved to be more clearly and consistently structured.
 +
 
 +
3) Extension points have moved:
 +
 
 +
a) org.eclipse.ecf.identity.namespace
 +
b) org.eclipse.ecf.containerFactory, and org.eclipse.ecf.startup
 +
c) org.eclipse.ecf.sharedobject.sharedObjectFactory
 +
 
 +
The connectionFactory extension point has been removed.
 +
 
 +
4) The datashare API has been simplified/made smaller and the dependency in the API on the sharedobject api has been removed.
 +
 
 +
5) All example and test code has been updated with above refactorings.
 +
 
 +
6) Internal packages have been defined with consistent naming to hold the Activator classes and other internal packages/classes.  There is more to do here, as I've focused so far only on identity and core plugins.
 +
 
 +
7) Created a more general Trace class (in org.eclipse.ecf.core.util in identity plugin) and moved over tracing in identity and core to new Trace.  More to do here for non core plugins.
 +
 
 +
8) Fixed and added javadocs for identity and core plugins.  See http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/
  
 
==='Low-end' Execution Environment Support===
 
==='Low-end' Execution Environment Support===
  
See: https://bugs.eclipse.org/bugs/show_bug.cgi?id=149024
+
See: Bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=149024 #149024]
  
 
'''Problem''':  Dependency on javax.security.auth.callback.* classes.  These classes are not available in Framework 1.1 (they are part of the JAAS classes that are optional for F1.1)
 
'''Problem''':  Dependency on javax.security.auth.callback.* classes.  These classes are not available in Framework 1.1 (they are part of the JAAS classes that are optional for F1.1)
Line 28: Line 76:
 
   javax.security.auth.callback.NameCallback;
 
   javax.security.auth.callback.NameCallback;
 
   javax.security.auth.callback.UnsupportedCallbackException;
 
   javax.security.auth.callback.UnsupportedCallbackException;
 
'''Status:  DONE'''
 
  
 
'''Explanation''':  Added new classes and changed existing references to above classes to classes in ECF org.eclipse.ecf.core.security package:
 
'''Explanation''':  Added new classes and changed existing references to above classes to classes in ECF org.eclipse.ecf.core.security package:
Line 38: Line 84:
 
   org.eclipse.ecf.core.security.UnsupportedCallbackException;
 
   org.eclipse.ecf.core.security.UnsupportedCallbackException;
  
===Add 'removeListener' methods===
+
===Assure JRE1.4 as EE for All Core Plug-ins===
 +
See: Bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=160805 #160805]
  
 +
<div style="border: 2px solid #8E87EB; padding: 6px;">This isn't necessarily correct as not all plug-ins should be J2SE-1.4 compliant (this is an awkward case since the issue is over a provider's library). Per the discussions on the dev-list, a provider should be allowed to be whatever EE it wants. I have renamed the header as "All Core Plug-ins" instead of "All Plugins". ''--Remy Suen''</div>
 +
<div style="border: 2px solid #8E87EB; padding: 6px;">Reading it over, I guess my statement above makes the bug I filed invalid since if a provider plug-in can be whatever EE is necessary, then there is no need to change the Smack library's compiler compliance down to 1.4. I guess the point here is that plug-ins should be consistent in their MANIFEST.MF and compiler settings. Since the Smack library can run on J2SE-1.4 and does not use 5.0 features (generics, foreach, etc.), then the entire project's settings should be set to J2SE-1.4. If it were to need J2SE-1.5, then both the MANIFEST.MF EE and the compiler should be set as such. Inconsistent settings creates confusion for everyone. ''--Remy Suen''</div>
 +
 +
===Add 'removeListener' methods===
 
Add removeListener methods in IChatRoomContainer (and in IPresenceContainer).  Also check
 
Add removeListener methods in IChatRoomContainer (and in IPresenceContainer).  Also check
 
other listener add and check for availability of remove methods.
 
other listener add and check for availability of remove methods.
See: https://bugs.eclipse.org/bugs/show_bug.cgi?id=160968
 
  
'''Status''':  Not Done
+
See: Bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=160968 #160968]
 
+
===Streamline ClientSOContainer===
+
Streamline handling of creating/passing in connect data for new kind of authentication. 
+
See : https://bugs.eclipse.org/bugs/show_bug.cgi?id=150398
+
 
+
'''Status''':  Not Done
+
 
+
===Move IInvitationListener===
+
Move (in presence API) access to IInvitationListener to IChatRoomManager rather than IPresenceContainer. 
+
See:  https://bugs.eclipse.org/bugs/show_bug.cgi?id=160137
+
 
+
'''Status''':  Not Done
+
  
 
===Introduce Convention for Container Adapters===
 
===Introduce Convention for Container Adapters===
Line 65: Line 103:
 
Will be:  I<whatever>ContainerAdapter
 
Will be:  I<whatever>ContainerAdapter
  
This way, it should be more obvious which interface in a given API plugin is the  
+
This way, it should be more obvious which interface in a given API plug-in is the container adapter that should be used for the call to IContainer.getAdapter(Class).
container adapter that should be use for the call to IContainer.getAdapter
+
  
'''Status''':  Not Done
+
===Move IInvitationListener===
 
+
Move (in presence API) access to IInvitationListener to IChatRoomManager rather than IPresenceContainer.
===Assure JRE1.4 as EE for All Core Plug-ins===
+
See:  https://bugs.eclipse.org/bugs/show_bug.cgi?id=160805
+
 
+
<div style="border: 2px solid #8E87EB; padding: 6px;">This isn't necessarily correct as not all plug-ins should be J2SE-1.4 compliant (this is an awkward case since the issue is over a provider's library). Per the discussions on the dev-list, a provider should be allowed to be whatever EE it wants. I have renamed the header as "All Core Plug-ins" instead of "All Plugins". ''--Remy Suen''</div>
+
<div style="border: 2px solid #8E87EB; padding: 6px;">Reading it over, I guess my statement above makes the bug I filed invalid since if a provider plug-in can be whatever EE is necessary, then there is no need to change the Smack library's compiler compliance down to 1.4. I guess the point here is that plug-ins should be consistent in their MANIFEST.MF and compiler settings. Since the Smack library can run on J2SE-1.4 and does not use 5.0 features (generics, foreach, etc.), then the entire project's settings should be set to J2SE-1.4. If it were to need J2SE-1.5, then both the MANIFEST.MF EE and the compiler should be set as such. Inconsistent settings creates confusion for everyone. ''--Remy Suen''</div>
+
 
+
==Application Refactorings and Rewrites==
+
  
===Example Collab Application===
+
See: Bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=160137 #160137]
Refactor and rewrite org.eclipse.ecf.example.collab plugin.  Also need to create RCP app from new
+
set of top-level plugins.
+
See: https://bugs.eclipse.org/bugs/show_bug.cgi?id=160633
+
  
Suggested Initial Set of Features:
+
==Deferred Items==
 +
None.
  
* Discovery of ECF generic, xmpp servers.
+
[[Category:Eclipse Communication Framework|API Refactoring]]
* Client runs ECF generic server (user decided)
+
* XMPP buddy list.  Combine Hyperbola and ECF buddy list features
+
* IRC, XMPP, ECF generic chat
+
* Bulletin Board API
+
* File Transfer
+
* XMPP Group chat
+
* UI Features for presence, IM, text chat.  See: https://bugs.eclipse.org/bugs/show_bug.cgi?id=110896 and https://bugs.eclipse.org/bugs/show_bug.cgi?id=110894 and https://bugs.eclipse.org/bugs/show_bug.cgi?id=106562 and https://bugs.eclipse.org/bugs/show_bug.cgi?id=112599
+
* Open Browser Links.  See: https://bugs.eclipse.org/bugs/show_bug.cgi?id=148874
+
* Text input/output font control
+
* URL Co-browsing
+
* Shared Whiteboard
+
* Event recording and playback
+
* <Please add more here>
+

Latest revision as of 21:44, 14 November 2006

Prior to 1.0, ECF will be going through a concerted API and exemplary applications refactoring and restructuring effort.

Items In Progress

Add Bulletin Board API to ECF Plugins and Features (Major)

Add Bulletin Board API. Remove EE 1.5 dependencies.

See: Bug #150756

API Review

An overwhelming number of classes in ECF at the moment are not being marked as internal packages. Whilst this may be the actual intent of the plug-ins, many of these non-internal classes are completely undocumented but are generated along with the published javadocs on the ECF website.

For this review, ECF code needs to clearly mark provisional APIs as being provisional, interfaces that should not be implemented by clients should have that stated clearly in the class level documentation, classes needs to be moved to internal packages (such as Trace, classes extending Plugin or AbstractUIPlugin, any others that are found during this review etc.), everything that has been approved as being public API needs to be marked with @since 1.0 when ECF 1.0 is released, and many others.

See API Central for further information Eclipse conventions and best practices for API development.

Completed Items

Streamline ClientSOContainer

Streamline handling of creating/passing in connect data for new kind of authentication.

See: Bug #150398

Create filetransfer plugin, remove fileshare plugin

Remove org.eclipse.ecf.fileshare API packages and classes.

Create a new plugin: org.eclipse.ecf.filetransfer.

Status: Started by SBL

Split org.eclipse.ecf Core Plugin into 2 or 3 Plugins (Major)

Refactor org.eclipse.ecf plugin into 2 or 3 plugins. This is a large refactoring effort. See discussion thread on mailing list: http://dev.eclipse.org/mhonarc/lists/ecf-dev/msg00399.html

1) The 'core plugin' (id: org.eclipse.ecf: 130K) is now been split into three plugins:

a) org.eclipse.ecf.identity (31K) b) org.eclipse.ecf (49K) c) org.eclipse.ecf.sharedobject (66K)

Now, b depends upon a, and c depends upon b.

All of the other API plugins (presence [23K], datashare, fileshare, discovery [10K]) now depend on *b* (and a) but *not* c.

2) Many classes and packages have changed and moved to be more clearly and consistently structured.

3) Extension points have moved:

a) org.eclipse.ecf.identity.namespace b) org.eclipse.ecf.containerFactory, and org.eclipse.ecf.startup c) org.eclipse.ecf.sharedobject.sharedObjectFactory

The connectionFactory extension point has been removed.

4) The datashare API has been simplified/made smaller and the dependency in the API on the sharedobject api has been removed.

5) All example and test code has been updated with above refactorings.

6) Internal packages have been defined with consistent naming to hold the Activator classes and other internal packages/classes. There is more to do here, as I've focused so far only on identity and core plugins.

7) Created a more general Trace class (in org.eclipse.ecf.core.util in identity plugin) and moved over tracing in identity and core to new Trace. More to do here for non core plugins.

8) Fixed and added javadocs for identity and core plugins. See http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/

'Low-end' Execution Environment Support

See: Bug #149024

Problem: Dependency on javax.security.auth.callback.* classes. These classes are not available in Framework 1.1 (they are part of the JAAS classes that are optional for F1.1)

Removed ECF core and all provider references to classes

  javax.security.auth.callback.Callback;
  javax.security.auth.callback.CallbackHandler;
  javax.security.auth.callback.NameCallback;
  javax.security.auth.callback.UnsupportedCallbackException;

Explanation: Added new classes and changed existing references to above classes to classes in ECF org.eclipse.ecf.core.security package:

  org.eclipse.ecf.core.security.Callback;
  org.eclipse.ecf.core.security.CallbackHandler;
  org.eclipse.ecf.core.security.NameCallback;
  org.eclipse.ecf.core.security.UnsupportedCallbackException;

Assure JRE1.4 as EE for All Core Plug-ins

See: Bug #160805

This isn't necessarily correct as not all plug-ins should be J2SE-1.4 compliant (this is an awkward case since the issue is over a provider's library). Per the discussions on the dev-list, a provider should be allowed to be whatever EE it wants. I have renamed the header as "All Core Plug-ins" instead of "All Plugins". --Remy Suen
Reading it over, I guess my statement above makes the bug I filed invalid since if a provider plug-in can be whatever EE is necessary, then there is no need to change the Smack library's compiler compliance down to 1.4. I guess the point here is that plug-ins should be consistent in their MANIFEST.MF and compiler settings. Since the Smack library can run on J2SE-1.4 and does not use 5.0 features (generics, foreach, etc.), then the entire project's settings should be set to J2SE-1.4. If it were to need J2SE-1.5, then both the MANIFEST.MF EE and the compiler should be set as such. Inconsistent settings creates confusion for everyone. --Remy Suen

Add 'removeListener' methods

Add removeListener methods in IChatRoomContainer (and in IPresenceContainer). Also check other listener add and check for availability of remove methods.

See: Bug #160968

Introduce Convention for Container Adapters

Change all occurrences of I<whatever>Container that are intended to be used as adapters off of IContainer (via IContainer.getAdapter(I<whatever>Container) to have the following naming convention:

Was: I<whatever>Container Will be: I<whatever>ContainerAdapter

This way, it should be more obvious which interface in a given API plug-in is the container adapter that should be used for the call to IContainer.getAdapter(Class).

Move IInvitationListener

Move (in presence API) access to IInvitationListener to IChatRoomManager rather than IPresenceContainer.

See: Bug #160137

Deferred Items

None.

Copyright © Eclipse Foundation, Inc. All Rights Reserved.