Mercurial > hg > release > thermostat-1.0
changeset 1311:5bb638ad064d
JavaDoc for new Decorator's stuff
review-thread: http://icedtea.classpath.org/pipermail/thermostat/2013-November/008687.html
reviewed-by: omajid
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/client/core/src/main/java/com/redhat/thermostat/client/ui/Decorator.java Fri Nov 08 14:23:57 2013 +0100 @@ -0,0 +1,83 @@ +/* + * Copyright 2012, 2013 Red Hat, Inc. + * + * This file is part of Thermostat. + * + * Thermostat is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published + * by the Free Software Foundation; either version 2, or (at your + * option) any later version. + * + * Thermostat is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Thermostat; see the file COPYING. If not see + * <http://www.gnu.org/licenses/>. + * + * Linking this code with other modules is making a combined work + * based on this code. Thus, the terms and conditions of the GNU + * General Public License cover the whole combination. + * + * As a special exception, the copyright holders of this code give + * you permission to link this code with independent modules to + * produce an executable, regardless of the license terms of these + * independent modules, and to copy and distribute the resulting + * executable under terms of your choice, provided that you also + * meet, for each linked independent module, the terms and conditions + * of the license of that module. An independent module is a module + * which is not derived from or based on this code. If you modify + * this code, you may extend this exception to your version of the + * library, but you are not obligated to do so. If you do not wish + * to do so, delete this exception statement from your version. + */ + +package com.redhat.thermostat.client.ui; + +import com.redhat.thermostat.common.Ordered; + +/** + * The {@link Decorator} interface offers a subtle, yet powerful way to + * decorate visual clues in the UI. + * + * <br /><br /> + * + * Control over when the decoration takes place is up to the client framework, + * generally the {@link Decorator} is queried any time there's an update on the + * state of the context the decorator refers to. + * + * <br /><br /> + * + * Also control on how the decoration is performed is up to the client. The + * implementation, though, can define the order of the decoration, and + * it is always guaranteed that the stacking order as defined by the + * {@link Ordered} interface is respected. This means that decorators with a + * lower index returned by {@link #getOrderValue()} will be executed first than + * decorators with an higher index. This is important to consider when some + * decorators want to define the base for other decorators or ensure that their + * information is property ordered. + * + * <br /><br /> + * + * While this represents the most powerful feature of decorators, it also + * introduce an inherent instability, so decorators should be appropriately + * tested in order to ensure there are no conflicts. + * + * <br /><br /> + * + * Clients will track for Decorator subclasses exported as OSGi services, where + * each subclass define the context of the decoration. The actual client + * implementation may then have more than one entry point for decoration, + * those entry point mark the actual target for the decorator itself. For this + * reason the {@link Decorator#ID} property needs to point to the appropriate + * value for the decoration. The value is client and context dependent. + */ +public interface Decorator extends Ordered { + + /** + * Property for OSGi services indicating the target for this decorator. + */ + public static final String ID = "Decorator_ID"; +}
--- a/client/core/src/main/java/com/redhat/thermostat/client/ui/ReferenceFieldIconDecorator.java Fri Nov 08 14:23:26 2013 +0100 +++ b/client/core/src/main/java/com/redhat/thermostat/client/ui/ReferenceFieldIconDecorator.java Fri Nov 08 14:23:57 2013 +0100 @@ -36,12 +36,25 @@ package com.redhat.thermostat.client.ui; -import com.redhat.thermostat.common.Ordered; +import com.redhat.thermostat.annotations.ExtensionPoint; +import com.redhat.thermostat.storage.core.HostRef; import com.redhat.thermostat.storage.core.Ref; -public interface ReferenceFieldIconDecorator extends Ordered { - - public static final String ID = "ReferenceFieldIconDecorator_ID"; +/** + * Implementations of this interface have the ability to decorate the specific + * targets by changing or replacing the target {@link PlatformIcon}. The {@link Ref} + * is passed to which the icon belong so that implementations can filter or + * change their behavior according to the reference being passed or its status. + * + * <br /><br /> + * + * For example, a decorator may decide to only decorate some specific type of + * {@link Ref}, like {@link HostRef} that currently don't have an agent + * connected. The code would then check for the actual type of the reference + * and check the state before passing on the updated icon. + */ +@ExtensionPoint +public interface ReferenceFieldIconDecorator extends Decorator { /** * The passed {@link PlatformIcon} my be null, indicating no plugin has
--- a/client/core/src/main/java/com/redhat/thermostat/client/ui/ReferenceFieldLabelDecorator.java Fri Nov 08 14:23:26 2013 +0100 +++ b/client/core/src/main/java/com/redhat/thermostat/client/ui/ReferenceFieldLabelDecorator.java Fri Nov 08 14:23:57 2013 +0100 @@ -36,18 +36,29 @@ package com.redhat.thermostat.client.ui; -import com.redhat.thermostat.common.Ordered; +import com.redhat.thermostat.annotations.ExtensionPoint; +import com.redhat.thermostat.storage.core.HostRef; import com.redhat.thermostat.storage.core.Ref; /** - * + * Implementations of this interface have the ability to decorate the specific + * targets by changing or replacing the target {@link String}. The {@link Ref} + * is passed to which the label belongs so that implementations can filter or + * change their behavior according to the reference being passed or its status. + * + * <br /><br /> + * + * For example, a decorator may decide to only decorate some specific type of + * {@link Ref}, like {@link HostRef} that currently don't have an agent + * connected. The code would then check for the actual type of the reference + * and check the state before passing on the updated {@link String}. */ -public interface ReferenceFieldLabelDecorator extends Ordered { +@ExtensionPoint +public interface ReferenceFieldLabelDecorator extends Decorator { - public static final String ID = "ReferenceFieldLabelDecorator_ID"; - /** - * The passed label my be null, indicating no plugin has set the label. + * The passed label my be null, indicating no plugin has set the label so + * far. */ String getLabel(String originalLabel, Ref reference); }
--- a/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/host/swing/DeadHostIconDecorator.java Fri Nov 08 14:23:26 2013 +0100 +++ b/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/host/swing/DeadHostIconDecorator.java Fri Nov 08 14:23:57 2013 +0100 @@ -58,7 +58,7 @@ @Override public int getOrderValue() { - return ORDER_DEFAULT_GROUP + 100; + return ORDER_FIRST + 100; } @Override
--- a/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/host/swing/HostIconDecorator.java Fri Nov 08 14:23:26 2013 +0100 +++ b/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/host/swing/HostIconDecorator.java Fri Nov 08 14:23:57 2013 +0100 @@ -46,12 +46,12 @@ public class HostIconDecorator implements ReferenceFieldIconDecorator { - private static final Icon ICON = IconUtils.resizeIcon(IconResource.HOST_24.getIcon()); + private static final Icon ICON = IconUtils.resizeIcon(IconResource.HOST_24.getIcon(), 32); private static final Icon SELECTED = CompositeIcon.createDefaultComposite(ICON, true); @Override public int getOrderValue() { - return ORDER_DEFAULT_GROUP; + return ORDER_FIRST; } @Override
--- a/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/host/swing/HostLabelDecorator.java Fri Nov 08 14:23:26 2013 +0100 +++ b/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/host/swing/HostLabelDecorator.java Fri Nov 08 14:23:57 2013 +0100 @@ -54,7 +54,7 @@ @Override public int getOrderValue() { - return ORDER_DEFAULT_GROUP; + return ORDER_FIRST; } @Override
--- a/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/host/swing/IconUtils.java Fri Nov 08 14:23:26 2013 +0100 +++ b/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/host/swing/IconUtils.java Fri Nov 08 14:23:57 2013 +0100 @@ -43,8 +43,8 @@ import com.redhat.thermostat.client.swing.components.Icon; public class IconUtils { - public static Icon resizeIcon(Icon source) { - Icon canvas = new EmptyIcon(32, 32); + public static Icon resizeIcon(Icon source, int size) { + Icon canvas = new EmptyIcon(size, size); float v1 = canvas.getIconWidth() / 2; float v0 = source.getIconWidth() / 2;
--- a/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/vm/swing/DeadVMIconDecorator.java Fri Nov 08 14:23:26 2013 +0100 +++ b/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/vm/swing/DeadVMIconDecorator.java Fri Nov 08 14:23:57 2013 +0100 @@ -63,7 +63,7 @@ @Override public int getOrderValue() { - return ORDER_DEFAULT_GROUP + 100; + return ORDER_FIRST + 100; } @Override
--- a/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/vm/swing/VMIconDecorator.java Fri Nov 08 14:23:26 2013 +0100 +++ b/client/living-vm-filter/swing/src/main/java/com/redhat/thermostat/client/filter/vm/swing/VMIconDecorator.java Fri Nov 08 14:23:57 2013 +0100 @@ -47,12 +47,12 @@ public class VMIconDecorator implements ReferenceFieldIconDecorator { - private static final Icon ICON = IconUtils.resizeIcon(IconResource.JAVA_APPLICATION_24.getIcon()); + private static final Icon ICON = IconUtils.resizeIcon(IconResource.JAVA_APPLICATION_24.getIcon(), 32); private static final Icon SELECTED = CompositeIcon.createDefaultComposite(ICON, true); @Override public int getOrderValue() { - return ORDER_DEFAULT_GROUP; + return ORDER_FIRST; } @Override
--- a/client/swing/src/main/java/com/redhat/thermostat/client/swing/ReferenceFieldDecoratorLayout.java Fri Nov 08 14:23:26 2013 +0100 +++ b/client/swing/src/main/java/com/redhat/thermostat/client/swing/ReferenceFieldDecoratorLayout.java Fri Nov 08 14:23:57 2013 +0100 @@ -36,9 +36,60 @@ package com.redhat.thermostat.client.swing; -public enum ReferenceFieldDecoratorLayout { +import com.redhat.thermostat.client.ui.Decorator; +import com.redhat.thermostat.client.ui.PlatformIcon; +import com.redhat.thermostat.client.ui.ReferenceFieldIconDecorator; +import com.redhat.thermostat.client.ui.ReferenceFieldLabelDecorator; +import com.redhat.thermostat.storage.core.Ref; + +/** + * This {@link Enum} marks {@link Decorator} target for + * {@link ReferenceFieldLabelDecorator}s and + * {@link ReferenceFieldIconDecorator}s. Each of those entry point represent + * a visual element in the reference list component for the Swing based client. + */ +public enum ReferenceFieldDecoratorLayout { + + /** + * Represents the main label portion to be decorated by + * {@link ReferenceFieldLabelDecorator}s. + * + * <br /><br /> + * + * The main label is the top most field for each entry in the + * {@link Ref}eference list, usually containing by default the name of + * the reference. + * + * <br /><br /> + * + * An example use for this field is the name of the target reference. + */ LABEL_MAIN, + + /** + * Represents the secondary label portion to be decorated by + * {@link ReferenceFieldLabelDecorator}. + * + * <br /><br /> + * + * This label is usually a smaller and less obvious visual component that + * helps better define the actual entry. It should not contain too much + * information to avoid cluttering the UI. + * + * <br /><br /> + * + * An example use of this field is an unique ID of some kind. + */ LABEL_INFO, + /** + * Represents the main {@link PlatformIcon} portion of the entry to be + * decorated by {@link ReferenceFieldIconDecorator}s. + * + * <br /><br /> + * + * This icon is the main icon characterising the component being shown, + * for example representing a particular application or device. + */ ICON_MAIN, }
--- a/common/core/src/main/java/com/redhat/thermostat/common/Ordered.java Fri Nov 08 14:23:26 2013 +0100 +++ b/common/core/src/main/java/com/redhat/thermostat/common/Ordered.java Fri Nov 08 14:23:57 2013 +0100 @@ -79,6 +79,16 @@ public static final int ORDER_USER_GROUP = 5000; /** + * Order group for services that should be executed first. + */ + public static final int ORDER_FIRST = ORDER_DEFAULT_GROUP; + + /** + * Order group for services that should be executed last. + */ + public static final int ORDER_LAST = Integer.MAX_VALUE; + + /** * Defines a value to be used for assigning an order to * services. A service with a lower order value will * be processed before a service of a higher order value. This