Backend


1   /*
2    *    Copyright 2004 Dusty Phillips
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package com.buchuki.ensmer.object;
17  
18  import java.io.Serializable  ;
19  import javax.media.j3d.BranchGroup;
20  import javax.swing.event.*;
21  import com.buchuki.annotations.*;
22  import com.buchuki.ensmer.EnsmerManager;
23  import com.buchuki.ensmer.builtin.Configurator;
24  import java.util.*;
25  
26  
27  /**
28   * Abstract class to represent an object backend in Ensmer. Backends are
29   * generally third party objects that are loaded by the <code>Backhoe</code>.
30   * They control data and have Serializable objects that can be stored at any
31   * time. Each backend is associated with an instance of a frontend that
32   * controls the 3D user view based on the backend data. Each time the backend
33   * changes data it should call the protect fireChangeEvent() method. This
34   * notifies the frontend that it may have to update the display based on the
35   * backend's data and notifies the prevayler that data needs to be
36   * serialized. All data that needs to be stored should be accessed through
37   * the custom Serializable object. This object will be reserialized every
38   * time the fireChangeEvent() method is called.
39   *
40   * @author   Dusty Phillips [dusty@buchuki.com]
41   */
42  public abstract class Backend {
43  
44      /**
45       * Construct a Backend. Set up the listener list and event. Maintain the ID
46       * for this Backend.
47       */
48      public Backend() {
49          changeEvent = new ChangeEvent(this);
50          this.id = id;
51      }
52  
53      /**
54       * Add a ChangeListener to the list of listeners.
55       *
56       * @param l  the listener to be added to the sint
57       */
58      public void addChangeListener(ChangeListener l) {
59          listenerList.add(ChangeListener.class, l);
60      }
61  
62      /**
63       * Remove a ChangeListener from the list of listeners
64       *
65       * @param l  Description of the Parameter
66       */
67      public void removeChangeListener(ChangeListener l) {
68          listenerList.remove(ChangeListener.class, l);
69      }
70  
71      /**
72       * Get the Serializable object from this Backend. This method should
73       * <strong>always</strong> return an up to date object of the type
74       * associated with this backend.
75       *
76       * @return   the serializable for this Backend
77       */
78      public abstract Serializable   getSerializable();
79  
80      /**
81       * Returns the backend identifier.
82       *
83       * @return   the identifier for this backend
84       */
85      public Long   getId() {
86          return id;
87      }
88      
89      /**
90       * Convenience method to set a property on the associated configurator object.
91       * This is easier than getting the configurator from the ConfigManager directly
92       *
93       * @param key the name of the property
94       * @param value the property value
95       */
96      public void setConfigProperty(String   key, String   value) {
97          Configurator conf = EnsmerManager.instance().getConfigManager().getConfigurator(getId());
98          conf.setProperty(key, value);
99      }
100     
101     /**
102      * Convenience method to get a property on the associated configurator object.
103      *
104      * @param key the name of the property to get the value for
105      */
106     public String   getConfigProperty(String   key) {
107         Configurator conf = EnsmerManager.instance().getConfigManager().getConfigurator(getId());
108         return conf.getProperty(key);
109     }
110     
111     /**
112      * Convenience method to get a property on the associated configurator object.
113      * If the property is null, then a default is returned instead
114      *
115      * @param key the name of the property to get the value for
116      * @param defaultVal the default value to return if that key does not exist
117      */
118     public String   getConfigProperty(String   key, String   defaultVal) {
119         String   prop = getConfigProperty(key);
120         return prop == null ? defaultVal : prop;
121     }
122     
123     /**
124      * Get a copy of all the Configurator properties. Writing to
125      * the properties object is not recommended, and does not update the
126      * original properties (use setConfigProperty instead)
127      *
128      * @return properties list from the Configurator
129      */
130     public Properties getConfigProperties() {
131         Properties props = new Properties();
132         Configurator conf = EnsmerManager.instance().getConfigManager().getConfigurator(getId());
133         List<String  > names = conf.getPropertyNames();
134         for (String   name : names) {
135             props.setProperty(name, conf.getProperty(name));
136         }
137         return props;
138     }
139     
140     /**
141      * If this object is meant to be manually added to the scene (as opposed
142      * to adding the object incidentally via some interaction with another
143      * object), this method should return a representation of the group
144      * (something akin to an icon) to be displayed in the area where items are
145      * added. This can be a complex object or a simple Text2D describing the
146      * type. This icon cannot (currently) be changed by the frontend. The default
147      * representation returns null.  This method should always return a new
148      * branchgroup, not a cached instance.
149      *
150      * @return a visual object to represent this particular class of backend,
151      * or null if this object should not be manually addable to the scene
152      */
153     public static BranchGroup getRepresentation() {
154         return null;
155     }
156         
157 
158     /**
159      * Set the id of this backend. This method should only be called once, by
160      * the Backhoe when a backend is instantiated. Calling this method more than
161      * one could have disasterous effects on the state of the system. This is a
162      * definite security problem that will have to be addressed (perhaps by
163      * making this method package-private and placing it in the
164      * com.buchuki.ensmer package, perhaps by passing this value to the
165      * constructor) in later versions of Ensmer.
166      *
167      * @param id  the identifier for this object
168      */
169     @CallOnce
170     @Optimize("Method should not be public")
171     public void setId(Long   id) {
172         if (this.id != null) {
173             throw new IllegalStateException  ("Identifier has already been set");
174         }
175         this.id = id;
176     }
177 
178     /**
179      * Fire a ChangeListener to all listening objects
180      */
181     protected void fireChangeEvent() {
182         Object  [] listeners = listenerList.getListenerList();
183         for (int i = listeners.length - 2; i >= 0; i -= 2) {
184             if (listeners[i] == ChangeListener.class) {
185                 ((ChangeListener) listeners[i + 1]).stateChanged(changeEvent);
186             }
187         }
188     }
189 
190     /**
191      * List of ChangeEventListeners for this Backend
192      */
193     private EventListenerList listenerList = new EventListenerList();
194 
195     /**
196      * The changeEvent to issue when some data has changed. This event can be
197      * reused because it doesn't contain any state information
198      */
199     private ChangeEvent changeEvent;
200 
201     /**
202      * The identifier for this Backend
203      */
204     private Long   id;
205 
206 }
207 
208
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags