bundles/org.simantics.utils.datastructures/src/org/simantics/utils/datastructures/hints/HintTracker.java

   1 /*******************************************************************************\r
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
   3  * in Industry THTH ry.\r
   4  * All rights reserved. This program and the accompanying materials\r
   5  * are made available under the terms of the Eclipse Public License v1.0\r
   6  * which accompanies this distribution, and is available at\r
   7  * http://www.eclipse.org/legal/epl-v10.html\r
   8  *\r
   9  * Contributors:\r
  10  *     VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.utils.datastructures.hints;\r
  13 \r
  14 /**\r
  15  * HintTracker is a helper class for tracking any hints of a single\r
  16  * IHintContext.\r
  17  * \r
  18  * <p>\r
  19  * The main purpose of this class is to enable very easy switching of the\r
  20  * tracked hint context. Only a call to the {@link #track(IHintContext)} method\r
  21  * is required. All hint listeners registered into the tracked will\r
  22  * automatically be switched to listen to the new context instead.\r
  23  * </p>\r
  24  * \r
  25  * <p>\r
  26  * The tracker is implemented using HintStack but the\r
  27  * {@link #addHintContext(IHintContext, int)} and\r
  28  * {@link #removeHintContext(IHintContext)} methods are disabled by throwing\r
  29  * {@link UnsupportedOperationException} in both. This is to prevent invalid use\r
  30  * of the class as it is only meant for tracking a single context and nothing\r
  31  * more. Otherwise this class functions exactly like {@link IHintStack} and\r
  32  * {@link IHintObservable} are specified to work.\r
  33  * </p>\r
  34  * \r
  35  * <p>\r
  36  * The implementation is thread-safe.\r
  37  * </p>\r
  38  * \r
  39  * <p>\r
  40  * Always be sure to {@link #untrack()} any IHintContext that you're tracking\r
  41  * after the tracker is no longer needed. Otherwise you will most likely have\r
  42  * invalid listeners within the tracked IHintContext resulting in erroneous\r
  43  * behavior.\r
  44  * </p>\r
  45  * \r
  46  * @author Tuukka Lehtonen\r
  47  */\r
  48 public class HintTracker extends HintStack implements IHintTracker {\r
  49     \r
  50     private IHintContext ctx;\r
  51 \r
  52     public HintTracker() {\r
  53     }\r
  54 \r
  55     public HintTracker(IHintContext ctx) {\r
  56         addHintContext(ctx, 0);\r
  57     }\r
  58 \r
  59     /* (non-Javadoc)\r
  60      * @see org.simantics.utils.datastructures.hints.IHintTracker#track(org.simantics.utils.datastructures.hints.IHintContext)\r
  61      */\r
  62     public synchronized final void track(IHintContext ctx) {\r
  63         IHintContext prevCtx = this.ctx;\r
  64         if (ctx == prevCtx)\r
  65             return;\r
  66         this.ctx = ctx;\r
  67 \r
  68         if (ctx != null) {\r
  69             if (ctx.equals(prevCtx)) {\r
  70                 // remove+add order is necessary in this case.\r
  71                 // add+remove would fail since the hint context would\r
  72                 // already be found in the hint stack.\r
  73                 super.removeHintContext(prevCtx);\r
  74                 super.addHintContext(ctx, 0);\r
  75             } else {\r
  76                 super.addHintContext(ctx, 0);\r
  77                 if (prevCtx != null)\r
  78                     super.removeHintContext(prevCtx);\r
  79             }\r
  80         } else {\r
  81             if (prevCtx != null)\r
  82                 super.removeHintContext(prevCtx);\r
  83         }\r
  84     }\r
  85     \r
  86     /* (non-Javadoc)\r
  87      * @see org.simantics.utils.datastructures.hints.IHintTracker#untrack()\r
  88      */\r
  89     public final void untrack() {\r
  90         track(null);\r
  91     }\r
  92     \r
  93     @Override\r
  94     public final void addHintContext(IHintContext hints, int priority) {\r
  95         throw new UnsupportedOperationException();\r
  96     }\r
  97 \r
  98     @Override\r
  99     public final boolean removeHintContext(IHintContext hints) {\r
 100         throw new UnsupportedOperationException();\r
 101     }\r
 102 \r
 103 }