[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [hono-dev] Definition of Hono's public API
|
> -----Original Message-----
> From: hono-dev-bounces@xxxxxxxxxxx <hono-dev-bounces@xxxxxxxxxxx> On
> Behalf Of Hudalla Kai (IOC/PAP-HU)
> Sent: Dienstag, 28. Januar 2020 15:22
> To: hono-dev@xxxxxxxxxxx
> Subject: 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?
Yes, sounds good.
Regarding the "service-base" module, as I see it, the following classes in "org/eclipse/hono/service" directly represent the device registry base classes:
---
auth/
AuthenticationService.java
credentials/
CredentialsService.java
EventBusCredentialsAdapter.java
deviceconnection/
DeviceConnectionService.java
EventBusDeviceConnectionAdapter.java
management/
credentials/
CredentialsManagementService.java
EventBusCredentialsManagementAdapter.java
device/
DeviceManagementService.java
EventBusDeviceManagementAdapter.java
(possibly also DeviceBackend.java)
tenant/
TenantManagementService.java
EventBusTenantManagementAdapter.java
(possibly also TenantBackend.java)
registration/
EventBusRegistrationAdapter.java
RegistrationService.java
tenant/
EventBusTenantAdapter.java
TenantService.java
---
Dependent on these are:
---
management
credentials
CommonCredential.java
GenericCredential.java
PasswordCredential.java
PskCredential.java
X509CertificateCredential.java
device
Device.java
tenant
Tenant.java
Id.java
OperationResult.java
Result.java
Util.java
EventBusService.java
---
So we could either mark these with Public API annotations or split the package accordingly (dependent classes could also be put in hono-core at some point).
>
>
> > 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
> _______________________________________________
> 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
Best regards
Carsten Lohmann
Bosch IoT Hub - Product Area IoT Platform (IOC/PAP-HU)
Bosch.IO GmbH | Ullsteinstr. 128 | 12109 Berlin | GERMANY | www.bosch.io
Sitz: Berlin, Registergericht: Amtsgericht Charlottenburg; HRB 148411 B
Aufsichtsratsvorsitzender: Dr.-Ing. Thorsten Lücke; Geschäftsführung: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne Reckling
