Mercurial > hg > release > thermostat-0.13
changeset 871:4ccae2248ed5
Add additional javadocs for public API
Add more javadocs for public API classes. Almost all the public classes
in thermostat-client* and thermostat-agent* modules should now have
javadocs. Some of thermostat-storage-core and thermostat-common-command
is documented too, though it's not complete.
Reviewed-by: neugens
Review-thread: http://icedtea.classpath.org/pipermail/thermostat/2012-December/004852.html
line wrap: on
line diff
--- a/agent/command/src/main/java/com/redhat/thermostat/agent/command/ConfigurationServer.java Mon Dec 17 15:52:20 2012 -0500 +++ b/agent/command/src/main/java/com/redhat/thermostat/agent/command/ConfigurationServer.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,7 @@ package com.redhat.thermostat.agent.command; +// FIXME document this class public interface ConfigurationServer { void startListening(String address);
--- a/agent/command/src/main/java/com/redhat/thermostat/agent/command/ReceiverRegistry.java Mon Dec 17 15:52:20 2012 -0500 +++ b/agent/command/src/main/java/com/redhat/thermostat/agent/command/ReceiverRegistry.java Mon Dec 17 20:18:56 2012 -0500 @@ -40,6 +40,9 @@ import com.redhat.thermostat.common.utils.ServiceRegistry; +/** + * Handles registering {@link RequestReceiver}s into the framework. + */ public class ReceiverRegistry { private ServiceRegistry<RequestReceiver> proxy;
--- a/agent/command/src/main/java/com/redhat/thermostat/agent/command/RequestReceiver.java Mon Dec 17 15:52:20 2012 -0500 +++ b/agent/command/src/main/java/com/redhat/thermostat/agent/command/RequestReceiver.java Mon Dec 17 20:18:56 2012 -0500 @@ -39,6 +39,15 @@ import com.redhat.thermostat.common.command.Request; import com.redhat.thermostat.common.command.Response; +/** + * Handles requests coming in through the command-channel. + * <p/> + * Classes wishing to handle requests coming in through the command channel + * should implement this class and register it using a + * {@link ReceiverRegistry}. + * + * @see ReceiverRegistry#registerReceiver(RequestReceiver) + */ public interface RequestReceiver { public Response receive(Request request);
--- a/agent/core/pom.xml Mon Dec 17 15:52:20 2012 -0500 +++ b/agent/core/pom.xml Mon Dec 17 20:18:56 2012 -0500 @@ -101,9 +101,6 @@ com.redhat.thermostat.utils, com.redhat.thermostat.utils.management, </Export-Package> - <Private-Package> - com.redhat.thermostat.backend.sample, - </Private-Package> <!-- Do not autogenerate uses clauses in Manifests --> <_nouses>true</_nouses> </instructions>
--- a/agent/core/src/main/java/com/redhat/thermostat/agent/Agent.java Mon Dec 17 15:52:20 2012 -0500 +++ b/agent/core/src/main/java/com/redhat/thermostat/agent/Agent.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,7 +36,6 @@ package com.redhat.thermostat.agent; -import java.util.ArrayList; import java.util.Map; import java.util.UUID; import java.util.concurrent.ConcurrentHashMap;
--- a/agent/core/src/main/java/com/redhat/thermostat/agent/JvmStatusListener.java Mon Dec 17 15:52:20 2012 -0500 +++ b/agent/core/src/main/java/com/redhat/thermostat/agent/JvmStatusListener.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.agent; +/** + * A listener that is notified when a JVM starts or is stopped. + */ public interface JvmStatusListener { public void jvmStarted(int pid);
--- a/agent/core/src/main/java/com/redhat/thermostat/backend/Backend.java Mon Dec 17 15:52:20 2012 -0500 +++ b/agent/core/src/main/java/com/redhat/thermostat/backend/Backend.java Mon Dec 17 20:18:56 2012 -0500 @@ -40,13 +40,13 @@ import java.util.Map; import java.util.Map.Entry; -import com.redhat.thermostat.backend.BackendRegistry; import com.redhat.thermostat.common.LaunchException; import com.redhat.thermostat.common.dao.DAOFactory; import com.redhat.thermostat.storage.core.Storage; /** - * Represents a monitoring back-end. + * Represents a plugin that runs on the agent and performs monitoring of host + * and applications. */ public abstract class Backend { @@ -72,7 +72,7 @@ */ protected final void setInitialConfiguration(Map<String, String> configMap) throws BackendLoadException { if (initialConfigurationComplete) { - throw new BackendLoadException("A backend may only receive initial configuration once."); + throw new BackendLoadException(id, "The backend " + id.toString() + "may only receive initial configuration once."); } for (Entry<String, String> e : configMap.entrySet()) { String key = e.getKey(); @@ -80,7 +80,7 @@ try { setConfigurationValue(key, value); } catch (IllegalArgumentException iae) { - throw new BackendLoadException("Attempt to set invalid backend configuration for " + getName() + throw new BackendLoadException(id, "Attempt to set invalid backend configuration for " + getName() + " backend. Key: " + key + " Value: " + value, iae); } }
--- a/agent/core/src/main/java/com/redhat/thermostat/backend/BackendID.java Mon Dec 17 15:52:20 2012 -0500 +++ b/agent/core/src/main/java/com/redhat/thermostat/backend/BackendID.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,10 +36,13 @@ package com.redhat.thermostat.backend; +/** + * The unique identifier that identifies a backend. + */ public class BackendID { - private String simpleName; - private String className; + private final String simpleName; + private final String className; public BackendID(String simpleName, String className) { this.simpleName = simpleName;
--- a/agent/core/src/main/java/com/redhat/thermostat/backend/BackendLoadException.java Mon Dec 17 15:52:20 2012 -0500 +++ b/agent/core/src/main/java/com/redhat/thermostat/backend/BackendLoadException.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,15 +36,26 @@ package com.redhat.thermostat.backend; +/** + * An error occurred when loading or initializing a backend + */ public class BackendLoadException extends Exception { private static final long serialVersionUID = 4057881401012295723L; - public BackendLoadException(String message) { + private final BackendID backendId; + + public BackendLoadException(BackendID backendId, String message) { super(message); + this.backendId = backendId; } - public BackendLoadException(String message, Throwable cause) { + public BackendLoadException(BackendID backendId, String message, Throwable cause) { super(message, cause); + this.backendId = backendId; + } + + public BackendID getBackend() { + return backendId; } }
--- a/agent/core/src/main/java/com/redhat/thermostat/utils/hostname/HostName.java Mon Dec 17 15:52:20 2012 -0500 +++ b/agent/core/src/main/java/com/redhat/thermostat/utils/hostname/HostName.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.utils.hostname; +/** + * Finds the current host name without doing a DNS lookup + */ public class HostName { static {
--- a/bundles/src/main/java/com/redhat/thermostat/bundles/OSGiRegistry.java Mon Dec 17 15:52:20 2012 -0500 +++ b/bundles/src/main/java/com/redhat/thermostat/bundles/OSGiRegistry.java Mon Dec 17 20:18:56 2012 -0500 @@ -47,7 +47,9 @@ import com.redhat.thermostat.common.cli.CommandInfoNotFoundException; import com.redhat.thermostat.common.cli.CommandInfoSource; - +/** + * A Service that provides features to load bundles for given command names. + */ public abstract class OSGiRegistry { public abstract void setPrintOSGiInfo(boolean printOSGiInfo);
--- a/client/command/src/main/java/com/redhat/thermostat/client/command/RequestQueue.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/command/src/main/java/com/redhat/thermostat/client/command/RequestQueue.java Mon Dec 17 20:18:56 2012 -0500 @@ -38,6 +38,13 @@ import com.redhat.thermostat.common.command.Request; +/** + * Service for sending commands to an agent. + * <p> + * This uses the command-channel to send a request to the agent. The request + * and response (if any) are processed asynchronously. An instance of this can + * be obtained from OSGi. + */ public interface RequestQueue { public void putRequest(Request request);
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/Filter.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/Filter.java Mon Dec 17 20:18:56 2012 -0500 @@ -37,8 +37,8 @@ package com.redhat.thermostat.client.core; /** - * Marker interface for filters of information sources (VMs, Hosts, etc.) - * + * A {@link Filter} decides if some information matches what this + * {@link Filter} is designed to work with. */ public interface Filter<T> {
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/InformationService.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/InformationService.java Mon Dec 17 20:18:56 2012 -0500 @@ -42,7 +42,9 @@ /** * Marker interface for information services. - * + * <p> + * An {@code InformationService} provides some sort of information about + * something. Plug-ins should normally implement this as a entry point. */ public interface InformationService<T extends Ref> { @@ -94,8 +96,15 @@ */ public int getPriority(); + /** + * Returns a {@link Filter} that is used to determine if this information + * source can provide information for a given target. + */ public Filter<T> getFilter(); + /** + * Returns the controller for this plugin's UI. + */ public InformationServiceController<T> getInformationServiceController(T ref); }
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/NameMatchingRefFilter.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/NameMatchingRefFilter.java Mon Dec 17 20:18:56 2012 -0500 @@ -40,6 +40,10 @@ import com.redhat.thermostat.common.dao.Ref; +/** + * A {@link Filter} that checks if the name of a {@link Ref} contains + * the supplied character substring. This is case sensitive. + */ public class NameMatchingRefFilter<T extends Ref> implements Filter<T> { private String pattern;
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/controllers/InformationServiceController.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/controllers/InformationServiceController.java Mon Dec 17 20:18:56 2012 -0500 @@ -40,8 +40,7 @@ import com.redhat.thermostat.common.dao.Ref; /** - * Marker interface for service controllers (VMs, Hosts, etc.) - * + * The UI controller for a view that provides some information about a Host or a VM. */ public interface InformationServiceController<T extends Ref> {
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/views/AgentInformationDisplayView.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/views/AgentInformationDisplayView.java Mon Dec 17 20:18:56 2012 -0500 @@ -40,6 +40,9 @@ import com.redhat.thermostat.common.ActionListener; +/** + * A view that displays an agent's information + */ public abstract class AgentInformationDisplayView extends BasicView implements UIComponent { public enum ConfigurationAction {
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/views/AgentInformationViewProvider.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/views/AgentInformationViewProvider.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.client.core.views; +/** + * Provides an AgentInformationViewProvider + */ public interface AgentInformationViewProvider extends ViewProvider { @Override
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/views/BasicView.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/views/BasicView.java Mon Dec 17 20:18:56 2012 -0500 @@ -39,6 +39,10 @@ import com.redhat.thermostat.common.ActionListener; import com.redhat.thermostat.common.ActionNotifier; +/** + * A {@link View} with support for notifying listeners on visibility + * changes. + */ public abstract class BasicView implements View { public enum Action { VISIBLE,
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/views/ClientConfigViewProvider.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/views/ClientConfigViewProvider.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.client.core.views; +/** + * A services that provides {@link ClientConfigurationView}s. + */ public interface ClientConfigViewProvider extends ViewProvider { @Override
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/views/ClientConfigurationView.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/views/ClientConfigurationView.java Mon Dec 17 20:18:56 2012 -0500 @@ -38,6 +38,9 @@ import com.redhat.thermostat.common.ActionListener; +/** + * A {@link View} for displaying and modifying client configuration. + */ public interface ClientConfigurationView extends View, UIComponent { enum Action {
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/views/HostInformationView.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/views/HostInformationView.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,7 +36,12 @@ package com.redhat.thermostat.client.core.views; - +/** + * A {@link View} that shows host information. It does not display + * this information directly. It relies on child views. + * + * @see VmInformationView + */ public abstract class HostInformationView extends BasicView implements UIComponent { public abstract void addChildView(String title, UIComponent view);
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/views/HostInformationViewProvider.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/views/HostInformationViewProvider.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.client.core.views; +/** + * This services provides an appropriate {@link HostInformationView}. + */ public interface HostInformationViewProvider extends ViewProvider { @Override
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/views/SummaryView.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/views/SummaryView.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,7 +36,9 @@ package com.redhat.thermostat.client.core.views; - +/** + * A {@link View} that displays a summary of everything in thermostat. + */ public abstract class SummaryView extends BasicView implements UIComponent { public abstract void setTotalHosts(String count);
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/views/ViewProvider.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/views/ViewProvider.java Mon Dec 17 20:18:56 2012 -0500 @@ -38,7 +38,9 @@ /** * Interface for View plugins to notify the controllers that the - * appropriate view have been registered in the framework. + * appropriate view have been registered in the framework. This allows + * creating {@link UIComponent}s appropriate for the widget toolkit in + * use. * * <br /><br /> *
--- a/client/core/src/main/java/com/redhat/thermostat/client/core/views/VmInformationViewProvider.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/core/views/VmInformationViewProvider.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.client.core.views; +/** + * A service that provides a {@link VmInformationView} + */ public interface VmInformationViewProvider extends ViewProvider { @Override
--- a/client/core/src/main/java/com/redhat/thermostat/client/ui/BytesTickUnit.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/ui/BytesTickUnit.java Mon Dec 17 20:18:56 2012 -0500 @@ -37,9 +37,14 @@ package com.redhat.thermostat.client.ui; import org.jfree.chart.axis.NumberTickUnit; +import org.jfree.chart.axis.TickUnit; import com.redhat.thermostat.common.utils.DisplayableValues; +/** + * A {@link TickUnit} that displays a byte value with an appropriate + * unit. + */ @SuppressWarnings("serial") public class BytesTickUnit extends NumberTickUnit {
--- a/client/core/src/main/java/com/redhat/thermostat/client/ui/ChartColors.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/ui/ChartColors.java Mon Dec 17 20:18:56 2012 -0500 @@ -38,7 +38,9 @@ import java.awt.Color; - +/** + * Provides access to a preselected set of colors for charts and graphs. + */ public class ChartColors { private static final Palette[] SERIES_COLORS = { Palette.PALE_RED,
--- a/client/core/src/main/java/com/redhat/thermostat/client/ui/Palette.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/core/src/main/java/com/redhat/thermostat/client/ui/Palette.java Mon Dec 17 20:18:56 2012 -0500 @@ -38,6 +38,10 @@ import java.awt.Color; +/** + * A set of preselected colors suitable for using to draw custom + * painting of charts graphs and figures. + */ public enum Palette { THERMOSTAT_BLU(new Color(74, 93, 117)),
--- a/client/swing/pom.xml Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/pom.xml Mon Dec 17 20:18:56 2012 -0500 @@ -148,9 +148,9 @@ com.redhat.thermostat.client.swing, com.redhat.thermostat.client.swing.components, com.redhat.thermostat.client.swing.components.models, - com.redhat.thermostat.client.swing.views, </Export-Package> <Private-Package> + com.redhat.thermostat.client.swing.views, com.redhat.thermostat.client.swing.internal, com.redhat.thermostat.client.swing.internal.components, com.redhat.thermostat.client.swing.internal.osgi,
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/IconResource.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/IconResource.java Mon Dec 17 20:18:56 2012 -0500 @@ -41,6 +41,9 @@ import javax.swing.Icon; import javax.swing.ImageIcon; +/** + * Provides asscess to various icons. + */ public class IconResource { /* FIXME we need to pick up the icons dynamically */
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/MenuHelper.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/MenuHelper.java Mon Dec 17 20:18:56 2012 -0500 @@ -54,6 +54,11 @@ import com.redhat.thermostat.common.utils.LoggingUtils; import com.redhat.thermostat.common.utils.StringUtils; +/** + * Helps adding or removing {@link MenuAction} from {@link JMenuBar}s. + * <p> + * This automatically handles creation and removal of submenus as appropriate. + */ public class MenuHelper { private static final Logger logger = LoggingUtils.getLogger(MenuHelper.class);
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/SwingComponent.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/SwingComponent.java Mon Dec 17 20:18:56 2012 -0500 @@ -40,6 +40,10 @@ import com.redhat.thermostat.client.core.views.UIComponent; +/** + * A {@link UIComponent} that uses the swing toolkit to display + * widgets and components. + */ public interface SwingComponent extends UIComponent { Component getUiComponent();
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/UIResources.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/UIResources.java Mon Dec 17 20:18:56 2012 -0500 @@ -42,6 +42,9 @@ import javax.swing.UIManager; import javax.swing.plaf.ColorUIResource; +/** + * Encapsulates a standard selection of colors and fonts. + */ public class UIResources { private static final UIResources resource = new UIResources();
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ActionButton.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ActionButton.java Mon Dec 17 20:18:56 2012 -0500 @@ -47,6 +47,9 @@ import javax.swing.JFrame; import javax.swing.SwingUtilities; +/** + * A swing implementation of {@link ToolbarButton}. + */ @SuppressWarnings("serial") public class ActionButton extends JButton implements ToolbarButton {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ChartPanel.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ChartPanel.java Mon Dec 17 20:18:56 2012 -0500 @@ -44,6 +44,11 @@ import org.jfree.chart.ChartRenderingInfo; import org.jfree.chart.JFreeChart; +/** + * A swing component that displays charts. + * + * @see org.jfree.chart.ChartPanel + */ @SuppressWarnings("serial") public class ChartPanel extends JPanel {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/EdtHelper.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/EdtHelper.java Mon Dec 17 20:18:56 2012 -0500 @@ -40,6 +40,15 @@ import java.lang.reflect.InvocationTargetException; import java.util.concurrent.Callable; +import javax.swing.SwingUtilities; + +/** + * Allows operations to be performed consistently on the Swing EDT + * irrespective of whether the caller is running on the EDT or not. + * + * @see SwingUtilities#invokeAndWait(Runnable) + * @see SwingUtilities#invokeLater(Runnable) + */ public class EdtHelper { @SuppressWarnings("serial") @@ -74,6 +83,13 @@ } } + /** + * Invoke the supplied {@link Runnable} on the EDT. + * @param r encapsulates the code to run + * @throws InvocationTargetException encapsulates the actual exception + * that occurs when executing this code. + * @throws InterruptedException + */ public void callAndWait(Runnable r) throws InvocationTargetException, InterruptedException { if (EventQueue.isDispatchThread()) { try { @@ -86,6 +102,14 @@ } } + /** + * Invokes the supplied {@link Callable} on the EDT, waits until it is + * finished execution and returns the result of invoking {@link Callable#call()}. + * @param c encapsulates the code to execute + * @return the result produce by c + * @throws InvocationTargetException indicates an exception occurred when executing the callable + * @throws InterruptedException + */ public <T> T callAndWait(Callable<T> c) throws InvocationTargetException, InterruptedException { CallableWrapper<T> w = new CallableWrapper<>(c); callAndWait(w);
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/EmptyIcon.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/EmptyIcon.java Mon Dec 17 20:18:56 2012 -0500 @@ -39,8 +39,12 @@ import java.awt.Component; import java.awt.Graphics; +import javax.swing.Icon; import javax.swing.ImageIcon; +/** + * A blank {@link Icon}. + */ @SuppressWarnings("serial") public class EmptyIcon extends ImageIcon {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/GradientPanel.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/GradientPanel.java Mon Dec 17 20:18:56 2012 -0500 @@ -45,7 +45,9 @@ import javax.swing.JPanel; - +/** + * A {@link JPanel} filled with a gradient color as the background. + */ @SuppressWarnings("serial") public class GradientPanel extends JPanel {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/GradientRoundBorder.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/GradientRoundBorder.java Mon Dec 17 20:18:56 2012 -0500 @@ -47,10 +47,14 @@ import javax.swing.UIManager; import javax.swing.border.AbstractBorder; +import javax.swing.border.Border; import javax.swing.plaf.UIResource; import com.redhat.thermostat.client.ui.Palette; +/** + * A round {@link Border} filled with a grandient paint. + */ @SuppressWarnings("serial") public class GradientRoundBorder extends AbstractBorder implements UIResource, Serializable {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/LabelField.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/LabelField.java Mon Dec 17 20:18:56 2012 -0500 @@ -39,6 +39,9 @@ import javax.swing.JLabel; import javax.swing.SwingConstants; +/** + * A {@link JLabel} appropriate for labelling other components. + */ @SuppressWarnings("serial") public class LabelField extends JLabel {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/SectionHeader.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/SectionHeader.java Mon Dec 17 20:18:56 2012 -0500 @@ -39,6 +39,10 @@ import javax.swing.JLabel; import javax.swing.SwingConstants; +/** + * A {@link JLabel} that is appropriate to use as a label for grouping + * the following information together. + */ @SuppressWarnings("serial") public class SectionHeader extends JLabel {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ShadowLabel.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ShadowLabel.java Mon Dec 17 20:18:56 2012 -0500 @@ -43,6 +43,9 @@ import javax.swing.JLabel; import javax.swing.plaf.metal.MetalLabelUI; +/** + * A {@link JLabel} that has a shadow. + */ @SuppressWarnings("serial") public class ShadowLabel extends JLabel {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/StatusBar.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/StatusBar.java Mon Dec 17 20:18:56 2012 -0500 @@ -46,6 +46,12 @@ import javax.swing.JPanel; import javax.swing.SwingUtilities; +/** + * A status bar used to display relevant information and status. + * <p> + * A status bar is normally displayed at the bottom of the main window. + * It may contain one or more areas displaying text and icons. + */ @SuppressWarnings("serial") public class StatusBar extends JPanel {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ThermostatPopupMenu.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ThermostatPopupMenu.java Mon Dec 17 20:18:56 2012 -0500 @@ -41,6 +41,9 @@ import javax.swing.JPopupMenu; import javax.swing.SwingUtilities; +/** + * A {@link JPopupMenu} with (optional) transparency. + */ @SuppressWarnings("serial") public class ThermostatPopupMenu extends JPopupMenu {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ThermostatTable.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ThermostatTable.java Mon Dec 17 20:18:56 2012 -0500 @@ -42,6 +42,10 @@ import javax.swing.JTable; import javax.swing.table.DefaultTableModel; +/** + * A table that tries to look and behave sensibly by default without + * requiring too much extra code from each plugin. + */ @SuppressWarnings("serial") public class ThermostatTable extends JTable {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ThermostatTableRenderer.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ThermostatTableRenderer.java Mon Dec 17 20:18:56 2012 -0500 @@ -40,9 +40,13 @@ import javax.swing.JTable; import javax.swing.table.DefaultTableCellRenderer; +import javax.swing.table.TableCellRenderer; import com.redhat.thermostat.client.ui.Palette; +/** + * A {@link TableCellRenderer} that colors rows to make them easier to read. + */ @SuppressWarnings("serial") public class ThermostatTableRenderer extends DefaultTableCellRenderer {
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ToolbarButton.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/ToolbarButton.java Mon Dec 17 20:18:56 2012 -0500 @@ -38,6 +38,9 @@ import javax.swing.AbstractButton; +/** + * A button that can be added to a toolbar. + */ public interface ToolbarButton { AbstractButton getToolbarButton(); void toggleText(boolean showText);
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/models/NullSelectionModel.java Mon Dec 17 15:52:20 2012 -0500 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/components/models/NullSelectionModel.java Mon Dec 17 20:18:56 2012 -0500 @@ -39,6 +39,9 @@ import javax.swing.ListSelectionModel; import javax.swing.event.ListSelectionListener; +/** + * Makes a JList non-selectable. + */ public class NullSelectionModel implements ListSelectionModel { @Override
--- a/common/command/src/main/java/com/redhat/thermostat/common/command/Message.java Mon Dec 17 15:52:20 2012 -0500 +++ b/common/command/src/main/java/com/redhat/thermostat/common/command/Message.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,7 +36,12 @@ package com.redhat.thermostat.common.command; - +/** + * Base interface for the various message types. + * + * @see Request + * @see Response + */ public interface Message { interface MessageType {
--- a/common/command/src/main/java/com/redhat/thermostat/common/command/Request.java Mon Dec 17 15:52:20 2012 -0500 +++ b/common/command/src/main/java/com/redhat/thermostat/common/command/Request.java Mon Dec 17 20:18:56 2012 -0500 @@ -45,9 +45,15 @@ /** * A Request object represents a request passed from a client - * to an agent. - * - * + * to an agent. Each request is separate, complete and unordered. The + * agent may or may not take an action when it receives a request. + * <p> + * Requests are meant for controlling the agent, not for asking an + * agent nor sending an agent any sort of data. + * <p> + * The following implementation details of this class are subject to + * change at any time. + * <p> * Request objects are serialized over the command channel in the following * format: *
--- a/common/command/src/main/java/com/redhat/thermostat/common/command/RequestResponseListener.java Mon Dec 17 15:52:20 2012 -0500 +++ b/common/command/src/main/java/com/redhat/thermostat/common/command/RequestResponseListener.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.common.command; +/** + * A listener that is notified of the response to given request. + */ public interface RequestResponseListener { public void fireComplete(Request request, Response response);
--- a/common/command/src/main/java/com/redhat/thermostat/common/command/Response.java Mon Dec 17 15:52:20 2012 -0500 +++ b/common/command/src/main/java/com/redhat/thermostat/common/command/Response.java Mon Dec 17 20:18:56 2012 -0500 @@ -39,16 +39,18 @@ /** * A Response object represents a response message passed from an agent - * to a client. - * - * + * to a client. Responses must not be used to send data; they reach only a + * specific client and are not recorded. + * <p> + * The implementation details of this class are subject to change at any time. + * <p> * Response objects are serialized over the command channel in the following * format: - * + * <pre> * ------------ * | A | TYPE | * ------------ - * + * </pre> * A is an 32 bit integer representing the length - in bytes - of TYPE. TYPE * is a byte array representing the string of the response type (e.g. * "OK"). @@ -80,7 +82,7 @@ AUTH_FAILED; } - ResponseType type; + private ResponseType type; public Response (ResponseType type) { this.type = type;
--- a/common/core/src/main/java/com/redhat/thermostat/common/ApplicationCache.java Mon Dec 17 15:52:20 2012 -0500 +++ b/common/core/src/main/java/com/redhat/thermostat/common/ApplicationCache.java Mon Dec 17 20:18:56 2012 -0500 @@ -39,12 +39,16 @@ import java.util.Map; import java.util.concurrent.ConcurrentHashMap; +/** + * A simple cache to keep resources in. + */ public class ApplicationCache { - @SuppressWarnings("rawtypes") - private Map cache = new ConcurrentHashMap(); + + // FIXME: Add some sort of support for evication of resources + // otherwise this 'cache' will become a memory leak + + private final Map<Object, Object> cache = new ConcurrentHashMap<>(); - - @SuppressWarnings("unchecked") public void addAttribute(Object key, Object value) { cache.put(key, value); }
--- a/common/core/src/main/java/com/redhat/thermostat/common/Clock.java Mon Dec 17 15:52:20 2012 -0500 +++ b/common/core/src/main/java/com/redhat/thermostat/common/Clock.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.common; +/** + * A clock. Useful for separating the source of time from a piece of code. + */ public interface Clock { /**
--- a/common/core/src/main/java/com/redhat/thermostat/common/SystemClock.java Mon Dec 17 15:52:20 2012 -0500 +++ b/common/core/src/main/java/com/redhat/thermostat/common/SystemClock.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.common; +/** + * A {@link Clock} that corresponds to the time as measured on the system. + */ public class SystemClock implements Clock { @Override
--- a/keyring/src/main/java/com/redhat/thermostat/utils/keyring/Credentials.java Mon Dec 17 15:52:20 2012 -0500 +++ b/keyring/src/main/java/com/redhat/thermostat/utils/keyring/Credentials.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.utils.keyring; +/** + * Data used to identify and authenticate a user. + */ public class Credentials implements Cloneable { private String userName;
--- a/keyring/src/main/java/com/redhat/thermostat/utils/keyring/Keyring.java Mon Dec 17 15:52:20 2012 -0500 +++ b/keyring/src/main/java/com/redhat/thermostat/utils/keyring/Keyring.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.utils.keyring; +/** + * Manages sensitive data, like {@link Credentials}, securely. + */ public interface Keyring { /**
--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Category.java Mon Dec 17 15:52:20 2012 -0500 +++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Category.java Mon Dec 17 20:18:56 2012 -0500 @@ -42,6 +42,9 @@ import java.util.Map; import java.util.Objects; +/** + * A bag of data + */ public class Category { private String name; private final Map<String, Key<?>> keys;
--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Cursor.java Mon Dec 17 15:52:20 2012 -0500 +++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Cursor.java Mon Dec 17 20:18:56 2012 -0500 @@ -38,6 +38,9 @@ import com.redhat.thermostat.storage.model.Pojo; +/** + * Allows traversing over objects obtained from Storage. + */ public interface Cursor<T extends Pojo> { boolean hasNext();
--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Entity.java Mon Dec 17 15:52:20 2012 -0500 +++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Entity.java Mon Dec 17 20:18:56 2012 -0500 @@ -41,6 +41,12 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * The presence of this annotation indicates that a class maybe serialized + * and stored into a {@link Storage}. Entities must be valid Java Beans. + * + * @see Persist + */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface Entity {
--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Persist.java Mon Dec 17 15:52:20 2012 -0500 +++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Persist.java Mon Dec 17 20:18:56 2012 -0500 @@ -41,6 +41,11 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Indicates that the annotated JavaBean property should be persisted into some + * form of storage when needed. Properties without this annotation will not be + * persisted. + */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface Persist {
--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Query.java Mon Dec 17 15:52:20 2012 -0500 +++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Query.java Mon Dec 17 20:18:56 2012 -0500 @@ -36,6 +36,9 @@ package com.redhat.thermostat.storage.core; +/** + * Describes what data should be fetched. + */ public interface Query { enum Criteria {
--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Remove.java Mon Dec 17 15:52:20 2012 -0500 +++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Remove.java Mon Dec 17 20:18:56 2012 -0500 @@ -37,7 +37,9 @@ package com.redhat.thermostat.storage.core; - +/** + * Describes what data should be removed from storage. + */ public interface Remove { Remove from(Category category);
--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Storage.java Mon Dec 17 15:52:20 2012 -0500 +++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Storage.java Mon Dec 17 20:18:56 2012 -0500 @@ -42,6 +42,11 @@ import com.redhat.thermostat.storage.model.AgentIdPojo; import com.redhat.thermostat.storage.model.Pojo; +/** + * A storage can be used to store, query, update and remove data. + * Implementations may use memory, a file, some database or even a network + * server as the backing store. + */ public interface Storage { void setAgentId(UUID id); @@ -52,6 +57,8 @@ Connection getConnection(); + // TODO why does putPojo have an agent id param but not updatePojo and removePojo? + void putPojo(Category category, boolean replace, AgentIdPojo pojo); void updatePojo(Update update);
--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Update.java Mon Dec 17 15:52:20 2012 -0500 +++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Update.java Mon Dec 17 20:18:56 2012 -0500 @@ -34,9 +34,11 @@ * to do so, delete this exception statement from your version. */ - package com.redhat.thermostat.storage.core; +/** + * Describes which data should be updated with what values + */ public interface Update { Update from(Category category);