search

tlaukkan / zigbee4java

Zigbee API for Java provides simple Java interface to ZigBee network.
Apache License 2.0
143 stars 68 forks source link

Package name conventions. API vs impl (maybe internal?) packages #70

Closed cdealti closed 8 years ago

cdealti commented 8 years ago

These are the imports of ZigBeeConsole:

import org.apache.commons.io.FileUtils;
import org.bubblecloud.zigbee.api.Device;
import org.bubblecloud.zigbee.api.DeviceListener;
import org.bubblecloud.zigbee.api.ZigBeeApiConstants;
import org.bubblecloud.zigbee.api.ZigBeeDeviceException;
import org.bubblecloud.zigbee.api.cluster.Cluster;
import org.bubblecloud.zigbee.api.cluster.general.LevelControl;
import org.bubblecloud.zigbee.api.cluster.general.OnOff;
import org.bubblecloud.zigbee.api.cluster.impl.api.core.Attribute;
import org.bubblecloud.zigbee.api.cluster.impl.api.core.ReportListener;
import org.bubblecloud.zigbee.api.cluster.impl.api.core.Reporter;
import org.bubblecloud.zigbee.api.cluster.impl.api.core.ZigBeeClusterException;
import org.bubblecloud.zigbee.api.cluster.general.ColorControl;
import org.bubblecloud.zigbee.network.NodeListener;
import org.bubblecloud.zigbee.network.ZigBeeNode;
import org.bubblecloud.zigbee.network.ZigBeeNodeDescriptor;
import org.bubblecloud.zigbee.network.ZigBeeNodePowerDescriptor;
import org.bubblecloud.zigbee.network.discovery.LinkQualityIndicatorNetworkBrowser.NetworkNeighbourLinks;
import org.bubblecloud.zigbee.network.discovery.ZigBeeDiscoveryManager;
import org.bubblecloud.zigbee.network.impl.ZigBeeNetworkManagerException;
import org.bubblecloud.zigbee.network.impl.ZigBeeNodeImpl;
import org.bubblecloud.zigbee.network.port.ZigBeePort;
import org.bubblecloud.zigbee.network.model.DiscoveryMode;
import org.bubblecloud.zigbee.util.Cie;

ZigBeeConsole needs to use many impl packages. What is the name convention here? Should we consider impl packages the same as internal (which should maybe preferred), something the application should try to avoid?

Pragmatically, the question arises from trying to OSGi-fy (see #62) the API with the maven-bundle-plugin. By default this plugin will not export packages containing impl or internal.

Also, I think that some of the classes imported above should be move in non impl packages, for example org.bubblecloud.zigbee.api.cluster.impl.api.core.Attribute it's just an interface and it's clearly part of the API.

Another example are Exceptions: org.bubblecloud.zigbee.api.cluster.impl.api.core.ZigBeeClusterException and org.bubblecloud.zigbee.network.impl.ZigBeeNetworkManagerException.

Also, I don't quite understand the overall name convention:

There are many other examples. We can improve a little bit the situation but that would mean breaking the current "API".

tlaukkan commented 8 years ago

Hi, the package structure can be refactored. Please let me know well in advance if you want to do it and execute in shortest possible order to avoid collisions ,)

cdjackson commented 8 years ago

Let’s make sure the versions are handled if we do a major change like this. I’m also ok with refactoring to make the library cleaner, but I think we need to make the versioning correct so we’re not caught out…

On 1 Apr 2016, at 23:21, Tommi S.E. Laukkanen notifications@github.com wrote:

Hi, the package structure can be refactored. Please let me know well in advance if you want to do it and execute in shortest possible order to avoid collisions ,)

— You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub https://github.com/tlaukkan/zigbee4java/issues/70#issuecomment-204590840

tlaukkan commented 8 years ago

Hi

Agreed. It would be nice to make a stable release as well. I think we got some of the bugs out now but more testing is needed...

-Tommi On 2 Apr 2016 15:59, "Chris Jackson" notifications@github.com wrote:

Let’s make sure the versions are handled if we do a major change like this. I’m also ok with refactoring to make the library cleaner, but I think we need to make the versioning correct so we’re not caught out…

On 1 Apr 2016, at 23:21, Tommi S.E. Laukkanen notifications@github.com wrote:

Hi, the package structure can be refactored. Please let me know well in advance if you want to do it and execute in shortest possible order to avoid collisions ,)

— You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub < https://github.com/tlaukkan/zigbee4java/issues/70#issuecomment-204590840>

— You are receiving this because you commented. Reply to this email directly or view it on GitHub https://github.com/tlaukkan/zigbee4java/issues/70#issuecomment-204712214

tlaukkan commented 8 years ago

Lets move the code related to the old ZigBee API to separate project. The Simple ZigBee API will not have these package structure issues.

tlaukkan commented 8 years ago

This has been fixed in v3 packaging. The legacy module packages still contain same structure for backwards compatibility.