From 612ba0c012e0ee6979b734adc8876612e756331c Mon Sep 17 00:00:00 2001 From: Marian Pohling Date: Tue, 10 Jan 2017 01:08:03 +0100 Subject: [PATCH] Wrote some more javadoc and fixed some doc gen errors. --- .../remote/service/AbstractServiceRemote.java | 70 ++++++++++++++++--- .../remote/service/ServiceRemoteFactory.java | 20 +++--- .../bco/dal/remote/unit/UnitRemote.java | 2 +- .../dal/remote/unit/UnitRemoteFactory.java | 3 +- .../openbase/bco/dal/remote/unit/Units.java | 5 +- 5 files changed, 76 insertions(+), 24 deletions(-) diff --git a/remote/src/main/java/org/openbase/bco/dal/remote/service/AbstractServiceRemote.java b/remote/src/main/java/org/openbase/bco/dal/remote/service/AbstractServiceRemote.java index 6c8af0e5..c0ec9458 100644 --- a/remote/src/main/java/org/openbase/bco/dal/remote/service/AbstractServiceRemote.java +++ b/remote/src/main/java/org/openbase/bco/dal/remote/service/AbstractServiceRemote.java @@ -50,13 +50,14 @@ import org.openbase.jul.schedule.SyncObject; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -import rst.domotic.action.ActionConfigType; +import rst.domotic.action.ActionConfigType.ActionConfig; import rst.domotic.service.ServiceTemplateType.ServiceTemplate.ServiceType; import rst.domotic.unit.UnitConfigType.UnitConfig; /** * * @author Divine Threepwood + * * @param generic definition of the overall service type for this remote. * @param the corresponding state for the service type of this remote. */ @@ -74,8 +75,9 @@ public abstract class AbstractServiceRemote observer) { + public void addDataObserver(final Observer observer) { serviceStateObservable.addObserver(observer); } @@ -133,7 +135,7 @@ public void addDataObserver(Observer observer) { * * @param observer the observer which has been registered */ - public void removeDataObserver(Observer observer) { + public void removeDataObserver(final Observer observer) { serviceStateObservable.removeObserver(observer); } @@ -169,8 +171,8 @@ public void init(final UnitConfig config) throws InitializationException, Interr * Each of the units referred by the given configurations should provide the service type of this service remote. * * @param configs a set of unit configurations. - * @throws InitializationException - * @throws InterruptedException + * @throws InitializationException is thrown if the service remote could not be initialized. + * @throws InterruptedException is thrown if the current thread is externally interrupted. */ public void init(final Collection configs) throws InitializationException, InterruptedException { try { @@ -192,6 +194,12 @@ public void init(final Collection configs) throws InitializationExce } } + /** + * {@inheritDoc} + * + * @throws CouldNotPerformException {@inheritDoc} + * @throws InterruptedException {@inheritDoc} + */ @Override public void activate() throws CouldNotPerformException, InterruptedException { try { @@ -210,6 +218,12 @@ public void activate() throws CouldNotPerformException, InterruptedException { } } + /** + * {@inheritDoc} + * + * @throws CouldNotPerformException {@inheritDoc} + * @throws InterruptedException {@inheritDoc} + */ @Override public void deactivate() throws CouldNotPerformException, InterruptedException { MultiException.ExceptionStack exceptionStack = null; @@ -224,6 +238,9 @@ public void deactivate() throws CouldNotPerformException, InterruptedException { MultiException.checkAndThrow("Could not deactivate all service units!", exceptionStack); } + /** + * {@inheritDoc} + */ @Override public void shutdown() { try { @@ -233,33 +250,63 @@ public void shutdown() { } } + /** + * {@inheritDoc} + * + * @return {@inheritDoc} + */ @Override public boolean isActive() { return unitRemoteMap.values().stream().allMatch((remote) -> (remote.isActive())); } + /** + * Returns the internal service factory which is used for the instance creation. + * + * @return the internal service factory. + */ public UnitRemoteFactory getFactory() { return factory; } - public void setFactory(UnitRemoteFactory factory) { + /** + * Set the internal service factory which will be used for the instance creation. + * + * @param factory the service factory. + */ + public void setFactory(final UnitRemoteFactory factory) { this.factory = factory; } + /** + * Returns a collection of all internally used unit remotes. + * + * @return a collection of unit remotes limited to the service interface. + */ public Collection getInternalUnits() { return Collections.unmodifiableCollection(unitRemoteMap.values()); } + /** + * Returns a collection of all internally used unit remotes. + * + * @return a collection of unit remotes limited to the service interface. + */ public Collection getServices() { return Collections.unmodifiableCollection(serviceMap.values()); } + /** + * Returns the service type of this remote. + * + * @return the remote service type. + */ public ServiceType getServiceType() { return serviceType; } @Override - public Future applyAction(final ActionConfigType.ActionConfig actionConfig) throws CouldNotPerformException, InterruptedException { + public Future applyAction(final ActionConfig actionConfig) throws CouldNotPerformException, InterruptedException { try { if (!actionConfig.getServiceType().equals(getServiceType())) { throw new VerificationFailedException("Service type is not compatible to given action config!"); @@ -299,7 +346,7 @@ public void waitForData() throws CouldNotPerformException, InterruptedException * @throws CouldNotPerformException is thrown in case the any error occurs, or if the given timeout is reached. In this case a TimeoutException is thrown. * @throws InterruptedException is thrown in case the thread is externally interrupted. */ - public void waitForData(long timeout, TimeUnit timeUnit) throws CouldNotPerformException, InterruptedException { + public void waitForData(final long timeout, final TimeUnit timeUnit) throws CouldNotPerformException, InterruptedException { //todo reimplement with respect to the given timeout. for (UnitRemote remote : unitRemoteMap.values()) { waitForData(timeout, timeUnit); @@ -329,6 +376,11 @@ public static boolean verifyServiceCompatibility(final UnitConfig unitConfig, fi return unitConfig.getServiceConfigList().stream().anyMatch((serviceConfig) -> (serviceConfig.getServiceTemplate().getType() == serviceType)); } + /** + * Returns a short instance description. + * + * @return a description as string. + */ @Override public String toString() { if (serviceType == null) { diff --git a/remote/src/main/java/org/openbase/bco/dal/remote/service/ServiceRemoteFactory.java b/remote/src/main/java/org/openbase/bco/dal/remote/service/ServiceRemoteFactory.java index 88e526a5..acd9b8b5 100644 --- a/remote/src/main/java/org/openbase/bco/dal/remote/service/ServiceRemoteFactory.java +++ b/remote/src/main/java/org/openbase/bco/dal/remote/service/ServiceRemoteFactory.java @@ -37,11 +37,11 @@ public interface ServiceRemoteFactory { * Creates and initializes a service remote out of the given service type * and a collection of unitConfigs. * - * @param serviceType - * @param unitConfigs + * @param serviceType The remote service type. + * @param unitConfigs The collection of units which are controlled by the new service remote instance. * @return the new created service remote. - * @throws CouldNotPerformException - * @throws java.lang.InterruptedException + * @throws CouldNotPerformException is thrown if any error occurs during the creation. + * @throws InterruptedException is thrown if the current thread is externally interrupted. */ public AbstractServiceRemote createAndInitServiceRemote(final ServiceType serviceType, final Collection unitConfigs) throws CouldNotPerformException, InterruptedException; @@ -49,20 +49,20 @@ public interface ServiceRemoteFactory { * Creates and initializes a service remote out of the given service type * and unitConfig. * - * @param serviceType - * @param unitConfig + * @param serviceType The remote service type. + * @param unitConfig The unit which is controlled by the new service remote instance. * @return the new created service remote. - * @throws CouldNotPerformException - * @throws java.lang.InterruptedException + * @throws CouldNotPerformException is thrown if any error occurs during the creation. + * @throws InterruptedException is thrown if the current thread is externally interrupted. */ public AbstractServiceRemote createAndInitServiceRemote(final ServiceType serviceType, final UnitConfig unitConfig) throws CouldNotPerformException, InterruptedException; /** * Creates a service remote out of the given service type. * - * @param serviceType + * @param serviceType The remote service type. * @return the new created unit remote. - * @throws CouldNotPerformException + * @throws CouldNotPerformException is thrown if any error occurs during the creation. */ public AbstractServiceRemote createServiceRemote(final ServiceType serviceType) throws CouldNotPerformException; } diff --git a/remote/src/main/java/org/openbase/bco/dal/remote/unit/UnitRemote.java b/remote/src/main/java/org/openbase/bco/dal/remote/unit/UnitRemote.java index e99514c2..d072e0cd 100644 --- a/remote/src/main/java/org/openbase/bco/dal/remote/unit/UnitRemote.java +++ b/remote/src/main/java/org/openbase/bco/dal/remote/unit/UnitRemote.java @@ -30,7 +30,7 @@ import rst.rsb.ScopeType; /** - * TODO Release: remove unused @param Configuration + * TODO Release: remove unused parameter CONFIG * * @author Divine Threepwood * @param Message diff --git a/remote/src/main/java/org/openbase/bco/dal/remote/unit/UnitRemoteFactory.java b/remote/src/main/java/org/openbase/bco/dal/remote/unit/UnitRemoteFactory.java index a44dfa59..d35a58a8 100644 --- a/remote/src/main/java/org/openbase/bco/dal/remote/unit/UnitRemoteFactory.java +++ b/remote/src/main/java/org/openbase/bco/dal/remote/unit/UnitRemoteFactory.java @@ -33,8 +33,9 @@ import rst.rsb.ScopeType.Scope; /** - * * @author Divine Threepwood + * + * The unit remote factory interface. */ public interface UnitRemoteFactory extends Factory { diff --git a/remote/src/main/java/org/openbase/bco/dal/remote/unit/Units.java b/remote/src/main/java/org/openbase/bco/dal/remote/unit/Units.java index f39886b2..1229743c 100644 --- a/remote/src/main/java/org/openbase/bco/dal/remote/unit/Units.java +++ b/remote/src/main/java/org/openbase/bco/dal/remote/unit/Units.java @@ -28,7 +28,6 @@ import org.openbase.bco.registry.unit.remote.CachedUnitRegistryRemote; import org.openbase.jul.exception.CouldNotPerformException; import org.openbase.jul.exception.FatalImplementationErrorException; -import org.openbase.jul.exception.InitializationException; import org.openbase.jul.exception.InvalidStateException; import org.openbase.jul.exception.NotAvailableException; import org.openbase.jul.exception.printer.ExceptionPrinter; @@ -212,7 +211,7 @@ public static UnitRemote getUnit(final String unitId, final boolean waitForData) * To force a resynchronization call {@link org.openbase.bco.dal.remote.unit.UnitRemote#requestData()} on the remote instance. * Please avoid polling unit states! If you want to get informed about unit config or unit data state changes, please register new config or data observer on this remote instance. * - * @param unitId the unit identifier. + * @param unitConfig the unit configuration. * @param waitForData if this flag is set to true the current thread will block until the unit remote is fully synchronized with the unit controller. * @return a new or cached unit remote which can be used to control the unit or request all current unit states. * @throws NotAvailableException is thrown in case the unit is not available. @@ -244,7 +243,7 @@ public static UnitRemote getUnit(final UnitConfig unitConfig, final boolean wait * * @see #getUnit(rst.domotic.unit.UnitConfigType.UnitConfig, boolean) */ - public static UR getUnit(final UnitConfig unitConfig, boolean waitForData, final Class unitRemoteClass) throws NotAvailableException, InterruptedException { + public static UR getUnit(final UnitConfig unitConfig, final boolean waitForData, final Class unitRemoteClass) throws NotAvailableException, InterruptedException { try { return (UR) getUnit(unitConfig, waitForData); } catch (ClassCastException ex) {