Bug 127081 - Add support in Database Explorer API to register server providers
Add support in Database Explorer API to register server providers
Status: RESOLVED WONTFIX
Product: db
Classification: Unclassified
Component: Code
6.x
All All
: P2 (vote)
: 6.x
Assigned To: apireviews
issues@db
: API, API_REVIEW_FAST
Depends on:
Blocks: 123351
  Show dependency treegraph
 
Reported: 2008-02-10 20:20 UTC by David Vancouvering
Modified: 2008-02-22 17:44 UTC (History)
0 users

See Also:
Issue Type: ENHANCEMENT
:


Attachments
Source change diffs (76.05 KB, text/plain)
2008-02-10 20:37 UTC, David Vancouvering
Details
Doc changes diffs (5.68 KB, text/plain)
2008-02-10 20:38 UTC, David Vancouvering
Details
Source change diffs, fixed (76.05 KB, text/plain)
2008-02-10 20:45 UTC, David Vancouvering
Details
Doc change diffs, fixed (5.68 KB, text/plain)
2008-02-10 20:45 UTC, David Vancouvering
Details

Note You need to log in before you can comment on or make changes to this bug.
Description David Vancouvering 2008-02-10 20:20:21 UTC
This issue is for the enhancement to the DB Explorer API for modules to register themselves in the layer as server
providers.
Comment 1 David Vancouvering 2008-02-10 20:25:26 UTC
This change does not impact modules that import the DB Explorer API or which the DB Explorer API depends on.  This is
adds an additional layer registration that we support.

We also create a new SPI called ServerProvider which extends the DatabaseRuntime SPI.  

This feature allows third party modules to register a server provider, which allows users to provide additional
functionality beyond start and stop.  In particular, it allows them to register the server as a node in the Database
Explorer and provide actions for this node.  It is through this mechanism, for example, that Java DB can appear as a
node under the Database Explorer (Services->Databases), and how we will provide functionality to be able to do basic
management of local MySQL and PostgreSQL servers.

JavaDoc for the new SPI, a description of the new layer, and full diffs of the changes will be provided.
Comment 2 David Vancouvering 2008-02-10 20:26:40 UTC
Javadoc for the new ServerProvider API:

/**
 * Represents an instance of a database server that can be managed. 
 *
 * <p>Implementations of this class should be put in the Databases/Servers folder
 * in the default filesystem.</p>
 * 
 * <p>If the implementation is registered and the canRegister() method returns
 * true, the server is added as a node to the Databases folder</p>
 *
 * @author David Van Couvering
 */
public interface ServerProvider extends DatabaseRuntime {

    /**
     * Return true if this server can be registered.  For example,
     * if it's not installed and/or not running, then the provider
     * may choose to return false.
     * 
     * If it returns true, then a node for the server will be displayed
     * under Services->Databases
     *  
     * @return true if a server is available, false otherwise
     */
    boolean canRegister();
    
    /**
     * @return a list of all actions this server supports
     */
    List getActions();
    
    /**
     * @return the display name for this provider
     */
    String getDisplayName();

    /**
     * @return a short description of this provider
     */
    public String getShortDescription();
}
Comment 3 David Vancouvering 2008-02-10 20:28:35 UTC
A provider registers an instance of ServerProvider under the filesystem under the Databases/Runtimes folder.  Note that
ServerProvider extends DatabaseRuntime, so the provider will also be used for the existing DatabaseRuntime functionality
(in particular, automatically starting the server when a connection is established).

Here is an example registration:

    <folder name="Databases">
        <folder name="Runtimes">
            <file name="DerbyServerProvider.instance">
                <attr name="instanceCreate" methodvalue="org.netbeans.modules.derby.DerbyServerProvider.getDefault"/>
                <attr name="instanceOf" stringvalue="org.netbeans.spi.db.explorer.ServerProvider"/>
            </file>
        </folder>
    </folder>
Comment 4 David Vancouvering 2008-02-10 20:36:06 UTC
The changes have been committed to my local repository.  They were in two different commits - one for the code changes
and one for the doc changes.  I am attaching both diffs.
Comment 5 David Vancouvering 2008-02-10 20:37:32 UTC
Created attachment 56392 [details]
Source change diffs
Comment 6 David Vancouvering 2008-02-10 20:38:02 UTC
Created attachment 56393 [details]
Doc changes diffs
Comment 7 David Vancouvering 2008-02-10 20:40:31 UTC
I would like some clarification on what to do with an addition to an API marked as stable.  I am concerned that this
automatically makes the new SPI stable, when I don't think it's at that place yet.  I marked it as "development" in the
architectural spec, but I'm not sure how this works and would appreciate your guidance.
Comment 8 David Vancouvering 2008-02-10 20:43:09 UTC
Apologies for the diffs, I specified the revisions in the wrong order in hg diff, so additions are represented as deletions.
Comment 9 David Vancouvering 2008-02-10 20:45:01 UTC
Created attachment 56394 [details]
Source change diffs, fixed
Comment 10 David Vancouvering 2008-02-10 20:45:47 UTC
Created attachment 56395 [details]
Doc change diffs, fixed
Comment 11 David Vancouvering 2008-02-10 20:46:36 UTC
The second set of diffs have additions and deletions represented correctly
Comment 12 David Vancouvering 2008-02-10 20:49:09 UTC
I think one more clarification is in order.  Not all providers will be able to start and stop the server.  When this is
the case, they should return "false" for canStart().  If the DatabaseRuntime detects that canStart() is false, it will
not attempt to start the server when the user tries to open a connection.
Comment 13 Pavel Buzek 2008-02-10 21:26:42 UTC
David, one module cannot have APIs of different stability levels. You also should not lower the stability level of an
existing API (once there is a contract that the API is stable and somebody relies on this there should be no surprises
for them). So there are only 2 ways (AFAICT): one is to make the new API stable, the other is to put the new API into a
separate module which would have a lower stability level.

I do not see any specific problems with the proposed extension. I suggest you try to get review by several other
developers and try to go for option 1 (stable API) because the other option would be very impractical (at least).
Comment 14 David Vancouvering 2008-02-11 04:42:50 UTC
Hm, that's too bad.  It gives me pause about making interfaces stable, as this affects an entire module.  We're going to
want to continue to expand db support, and if that means that any new interfaces we want to introduce have to be
immediately stable, it seems a little risky...

But you're right, putting this in another module is not really a viable option, so committing to Stable immediately is
really the only choice I have.  

Comment 15 David Vancouvering 2008-02-11 05:00:39 UTC
Can this interface change while NetBeans 6.1 is still not generally available?  For example, I may find I want to add
some more methods to the ServerProvider interface.  Is that permissible prior to GA, or will I need to create another
new interface once I check in the original one?  Please say yes I can change it before GA ... :)
Comment 16 Pavel Buzek 2008-02-11 08:19:42 UTC
Yes, before GA it can change. You should pass any change through a review, of course.
Comment 17 Andrei Badea 2008-02-11 10:09:30 UTC
AB01: since it seems the proposed API is going to change, I suggest moving it to the dbapi module, which only exposes a
friend API.

AB02: the methods of the proposed ServerProvider interface seems to map the methods needed to create a node for the
respective server provider (getActions(), getShortDescription(), getDisplayName()). Perhaps better for the interface to
just return a Node.

AB03: better for ServerProvider to avoid implementing DatabaseRuntime. That interface is meant for starting a server
when connecting to a database. As such, it can be implemented by a server-providing module separately. For starting a
stopping a server as a response to Start and Stop actions in the UI, I can think of two solutions:

- separate the isRunning(), canStart(), start() and stop() methods from DatabaseRuntime into a ServerStartStop interface
and have the server provider implement it. This allows the DB Explorer to start a server programmatically.

- do nothing and just expect the server-providing module to provide Start and Stop actions on the server node. I like
this approach more, since I don't know an use case (other than the one already covered by DatabaseRuntime) requiring the
DB Explorer to start a server programmatically.
Comment 18 David Vancouvering 2008-02-11 17:34:25 UTC
I talked to Andrei on the phone, and he explained to me how the dbapi module has an implementation dependency on db
module, and thus can use internal packages.  Then you can create new apis that are available to friends only.

So I'm going to migrate this new SPI to the dbapi module.  I also liked Andrei's suggestion that we keep it simple and
just make it a node registration API, reducing the amount of inter-module dependencies.

This change makes the API non-public and thus not up for API review.  I will keep this issue open for a week to see if
there are any further comments, and then will close it with WONTFIX.
Comment 19 Jaroslav Tulach 2008-02-12 08:16:09 UTC
'This change makes the API non-public and thus not up for API review." - this seems to imply to me that only public 
API needs review. This is not quite true, even less stable APIs may deserve a review: 
http://openide.netbeans.org/tutorial/api-design.html#category-friend
Comment 20 Andrei Badea 2008-02-12 10:46:00 UTC
Agreed, but it's not the case here, when the only client of the new API (the Java DB module) is in the database area
too, and other clients will probably be developed by the same team.
Comment 21 David Vancouvering 2008-02-22 17:44:33 UTC
Made this a new API in friend dbapi instead.


By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo