Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [hono-dev] Definition of Hono's public API

On 28.01.20 10:44, Jens Reimann wrote:
> Yes, I agree that the service-base mobile is a rather large chunk of code.
> 
> Personally I think it would make sense breaking it up into smaller
> pieces. Which would also make it easier to declare what is public, and
> what not.
> 

Placing all the public classes into a separate module/jar certainly
makes sense. However, IMHO in order to do that we first need to identify
the classes that we consider public API.

My understanding so far is that we agree that the core and client
modules are public API. In addition, all remote API definitions and the
protocol adapters' device-side interfaces are public API as well.
However, the protocol adapter implementions are *not* public API.

Based on the further assumption that we also want to provide the device
registry base classes as public API, we could take the following approach:
Start from those base classes and determine all classes/interfaces that
they depend on either directly or transitively within the service-base
module. All these classes/interfaces are then part of the public API
while all the remaining classes/interfaces of service-base are private API.

Based on this partitioning we can then see if we are able to create a
separate module for just the public API without creating split packages
or if we also need to move some classes to other packages before doing so.

Would that work for everybody?


> Maybe a quick solution to that is to not declare the service-base module
> public. And split the module into smaller chunks for 1.2.x. We could
> still provide a "fat jar", composed of the other JARs for 1.2, to make
> it easier to migrate.

> On Mon, Jan 27, 2020 at 5:15 PM Dejan Bosanac <dejanb@xxxxxxxxxxxx
> <mailto:dejanb@xxxxxxxxxxxx>> wrote:
> 
>     Hi Kai,
> 
>     I still think there are a lot of interfaces/classes in service-base
>     module that we should consider the public API. All device registry
>     and device connection services definitions live there.
> 
>     On Wed, Jan 22, 2020 at 9:41 AM Hudalla Kai (IOC/PAP-HU)
>     <Kai.Hudalla@xxxxxxxx <mailto:Kai.Hudalla@xxxxxxxx>> wrote:
> 
>         Sorry, forgot to add the links ...
> 
>         Based on the discussions I had with Carsten regarding the changes
>         necessary for [1] I can now also imagine to only define the
>         classes of
>         the core and client modules as part of Hono's Public API.
> 
>         Dejan had already raised some concerns regarding the impact it would
>         have on our ability to quickly evolve, if we declared too much
>         of our
>         code as part of the public API. I now see his point more clearly
>         as it
>         would basically prevent us from making any reasonably complex
>         changes to
>         any of our adapters without creating a new major release, which is
>         probably not what we want. Most of our adapters heavily depend on
>         classes in the service-base module so in order to make any
>         substantial
>         progress we will need to change many of the classes in there.
> 
>         In the past we had encouraged people to create custom protocol
>         adapters
>         by means of extending some of the base classes in service-base.
>         However,
>         in reality it seems more practical to use the approach outlined
>         in [2]
>         in order to connect devices using a proprietary protocol to a Hono
>         system. Note that this approach does not require implementing a full
>         fledged custom protocol adapter.
> 
>         I would therefore propose to also exclude the service-base
>         module from
>         Hono's public API. People can still use it if they want to
>         implement a
>         custom adapter but they should be aware that we might change the
>         code at
>         any time.
> 
>         WDYT?
> 
>         [1] https://github.com/eclipse/hono/issues/1328
>         [2] https://github.com/eclipse/hono/issues/1478
> 
>         Kai
> 
>         On 15.01.20 14:22, Hudalla Kai (INST/ECS4) wrote:
>         > On 15.01.20 12:56, Dejan Bosanac wrote:
>         >> Hi Kai,
>         >>
>         >> this seems reasonable to me. Just one thing, when you say
>         "all classes",
>         >> do you mean public methods signatures by that or something else?
>         >>
>         >
>         > Good point. I would say that this affects all public classes
>         in the
>         > "public" packages which are currently
>         >
>         > core: all packages
>         >
>         > client: all packages
>         >
>         > service-base: all packages
>         >
>         > Does that make sense?
>         >
>         >> On Tue, Jan 14, 2020 at 8:52 AM Hudalla Kai (INST/ECS4)
>         >> <Kai.Hudalla@xxxxxxxx <mailto:Kai.Hudalla@xxxxxxxx>
>         <mailto:Kai.Hudalla@xxxxxxxx <mailto:Kai.Hudalla@xxxxxxxx>>> wrote:
>         >>
>         >>     Hi list,
>         >>
>         >>     with Hono 1.0.0 having been released last year, we now
>         need to follow
>         >>     semantic versioning for its public API. So far so good.
>         During the past
>         >>     weeks while implementing new features, we already ran in
>         to situations
>         >>     where some refactoring would have been beneficial but
>         where we had to
>         >>     think twice about whether we can simply change a method's
>         signature or
>         >>     remove some obsolete class(es). I think we can all agree
>         that this
>         >>     depends on whether the affected artifacts are to be
>         considered part of
>         >>     Hono's public API or not.
>         >>
>         >>     However, we haven't yet defined which parts of Hono
>         actually constitute
>         >>     its public API. Thus, I would like to propose a draft of
>         what I would
>         >>     consider (or like to see as) part of Hono's public API:
>         >>
>         >>     1) All remote APIs documented under [1]
>         >>     2) All classes in the core module
>         >>     3) All classes in the client module
>         >>     4) All classes in the service-base module
>         >>
>         >>     IMHO the rest would then automatically not be public API
>         and would thus
>         >>     not be subject to semantic versioning.
>         >>
>         >>     WDYT?
>         >>
>         >>     [1] https://www.eclipse.org/hono/docs/api/
>         >>
>         >>     --
>         >>     Mit freundlichen Grüßen / Best regards
>         >>
>         >>     Kai Hudalla
>         >>
>         >>     Software Developer - Bosch IoT Hub
>         >>
>         >>     Bosch.IO GmbH
>         >>     Ullsteinstr. 128
>         >>     12109 Berlin
>         >>     GERMANY
>         >>     www.bosch.io <http://www.bosch.io> <http://www.bosch.io>
>         >>
>         >>     Registered Office: Berlin, Registration Court: Amtsgericht
>         >>     Charlottenburg; HRB 148411 B
>         >>     Chairman of the Supervisory Board: Dr.-Ing. Thorsten Lücke;
>         >>     Managing Directors: Dr. Stefan Ferber, Dr. Aleksandar
>         Mitrovic, Yvonne
>         >>     Reckling
>         >>     _______________________________________________
>         >>     hono-dev mailing list
>         >>     hono-dev@xxxxxxxxxxx <mailto:hono-dev@xxxxxxxxxxx>
>         <mailto:hono-dev@xxxxxxxxxxx <mailto:hono-dev@xxxxxxxxxxx>>
>         >>     To change your delivery options, retrieve your password, or
>         >>     unsubscribe from this list, visit
>         >>     https://www.eclipse.org/mailman/listinfo/hono-dev
>         >>
>         >>
>         >>
>         >> --
>         >> Regards
>         >> --
>         >> Dejan Bosanac
>         >> http://sensatic.net/about
>         >>
>         >> _______________________________________________
>         >> hono-dev mailing list
>         >> hono-dev@xxxxxxxxxxx <mailto:hono-dev@xxxxxxxxxxx>
>         >> To change your delivery options, retrieve your password, or
>         unsubscribe from this list, visit
>         >> https://www.eclipse.org/mailman/listinfo/hono-dev
>         >>
>         >
> 
>         -- 
>         Mit freundlichen Grüßen / Best regards
> 
>         Kai Hudalla
> 
>         Software Developer - Bosch IoT Hub
> 
>         Bosch.IO GmbH
>         Ullsteinstr. 128
>         12109 Berlin
>         GERMANY
>         www.bosch.io <http://www.bosch.io>
> 
>         Registered Office: Berlin, Registration Court: Amtsgericht
>         Charlottenburg; HRB 148411 B
>         Chairman of the Supervisory Board: Dr.-Ing. Thorsten Lücke;
>         Managing Directors: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic,
>         Yvonne
>         Reckling
>         _______________________________________________
>         hono-dev mailing list
>         hono-dev@xxxxxxxxxxx <mailto:hono-dev@xxxxxxxxxxx>
>         To change your delivery options, retrieve your password, or
>         unsubscribe
>         from this list, visit
>         https://www.eclipse.org/mailman/listinfo/hono-dev
>         _______________________________________________
>         hono-dev mailing list
>         hono-dev@xxxxxxxxxxx <mailto:hono-dev@xxxxxxxxxxx>
>         To change your delivery options, retrieve your password, or
>         unsubscribe from this list, visit
>         https://www.eclipse.org/mailman/listinfo/hono-dev
> 
> 
> 
>     -- 
>     Regards
>     --
>     Dejan Bosanac
>     http://sensatic.net/about
>     _______________________________________________
>     hono-dev mailing list
>     hono-dev@xxxxxxxxxxx <mailto:hono-dev@xxxxxxxxxxx>
>     To change your delivery options, retrieve your password, or
>     unsubscribe from this list, visit
>     https://www.eclipse.org/mailman/listinfo/hono-dev
> 
> 
> 
> -- 
> Jens Reimann
> Principal Software Engineer / EMEA ENG Middleware
> Werner-von-Siemens-Ring 14
> 85630 Grasbrunn
> Germany
> phone: +49 89 2050 71286
> _____________________________________________________________________________
> 
> Red Hat GmbH, www.de.redhat.com <http://www.de.redhat.com>,
> Registered seat: Grasbrunn, Commercial register: Amtsgericht Muenchen,
> HRB 153243,
> Managing Directors: Charles Cachera, Laurie Krebs, Michael O'Neill,
> Thomas Savage
> 
> _______________________________________________
> hono-dev mailing list
> hono-dev@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe from this list, visit
> https://www.eclipse.org/mailman/listinfo/hono-dev
> 

-- 
Mit freundlichen Grüßen / Best regards

Kai Hudalla

Software Developer - Bosch IoT Hub

Bosch.IO GmbH
Ullsteinstr. 128
12109 Berlin
GERMANY
www.bosch.io

Registered Office: Berlin, Registration Court: Amtsgericht
Charlottenburg; HRB 148411 B
Chairman of the Supervisory Board: Dr.-Ing. Thorsten Lücke;
Managing Directors: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne
Reckling

Back to the top