[
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 15:54, Lohmann Carsten (IOC/PAP-HU) wrote:
>> -----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
> ---
>
What about
management/
credentials/
CredentialsManagementHttpEndpoint
device/
DeviceManagementHttpEndpoint
tenant/
TenantManagementHttpEndpoint
>
> Dependent on these are:
Is suppose you mean that the base classes above depend on the following
classes/interfaces below, right?
> ---
> 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).
If I am not mistaken then there are other (private) classes remaining in
the above packages so we would actually create split packages if me
moved the public API classes to a separate module/jar.
>
>
>>
>>
>>> 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
>
> _______________________________________________
> 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
