AbstractSVGList


1   /*
2   
3      Copyright 2003-2004  The Apache Software Foundation 
4   
5      Licensed under the Apache License, Version 2.0 (the "License");
6      you may not use this file except in compliance with the License.
7      You may obtain a copy of the License at
8   
9          http://www.apache.org/licenses/LICENSE-2.0
10  
11     Unless required by applicable law or agreed to in writing, software
12     distributed under the License is distributed on an "AS IS" BASIS,
13     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14     See the License for the specific language governing permissions and
15     limitations under the License.
16  
17   */
18  package org.apache.batik.dom.svg;
19  
20  import java.util.ArrayList  ;
21  import java.util.Iterator  ;
22  import java.util.List  ;
23  
24  import org.apache.batik.parser.ParseException;
25  import org.w3c.dom.DOMException  ;
26  import org.w3c.dom.svg.SVGException;
27  
28  
29  /**
30   * This class is a base implementation for a live
31   * list representation of SVG attributes.
32   *
33   * This classe provides support for a SVG List
34   * representation of an attribute. It implements
35   * the basic functionnalities.
36   *
37   * For a specific attribute, it requires a 
38   * {@link #getValueAsString() attribute value},
39   * a {@link #doParse(String,ListHandler) parser},
40   * and the {@link #createSVGItem(Object) item creation}
41   *
42   * Whenever the attribute changes outside of
43   * the control of the list, this list must be
44   * {@link #invalidate invalidated }
45   *
46   * @author <a HREF="mailto:nicolas.socheleau@bitflash.com">Nicolas Socheleau</a>
47   * @version $Id: AbstractSVGList.java,v 1.7 2005/03/27 08:58:32 cam Exp $
48   */
49  public abstract class AbstractSVGList {
50  
51      /**
52       * Whether this list is valid.
53       */
54      protected boolean valid;
55  
56      /**
57       * List of item
58       */
59      protected List   itemList;
60  
61      /**
62       * Return the separator for the item is the list.
63       *
64       * @return separator of items in the list
65       */
66      protected abstract String   getItemSeparator();
67  
68      /**
69       * Return the item to be placed in the list.
70       *
71       * According to the parameter of the real SVGList
72       * represented here by an <code>Object</code>
73       * the implementation provide an item to be placed
74       * in the list.
75       *
76       * @param newItem paramter of the modification method
77       *   of the list
78       *
79       * @return an item to be placed in the list.
80       */
81      protected abstract SVGItem createSVGItem(Object   newItem);
82  
83      /**
84       * Parse the value of the attribute and build a list.
85       *
86       * Use a dedicated parser for the attribute and the list
87       * handler to build the list.
88       *
89       * @param value value of the attribute to be parsed
90       * @param builder list handler to create the list
91       */
92      protected abstract void doParse(String   value, ListHandler builder)
93          throws ParseException;
94  
95      /**
96       * Check the type of the element added to the list.
97       *
98       * @param newItem object to test
99       */
100     protected abstract void checkItemType(Object   newItem)
101         throws SVGException;
102 
103 
104     /**
105      * Return the <code>String</code> value associated
106      * to the attribute in the DOM.
107      *
108      * @return value of the attribute
109      */
110     protected abstract String   getValueAsString();
111 
112     /**
113      * Apply the changes of the list to the 
114      * attribute this list represents.
115      *
116      * @param value new value of the attribute
117      *   the value can be null if no item
118      *   are present in the list.
119      */
120     protected abstract void setAttributeValue(String   value);
121 
122     /**
123      * Create a DOM Exception.
124      */
125     protected abstract DOMException   createDOMException(short    type,
126                                                        String     key,
127                                                        Object  [] args);
128 
129     /**
130      * Creates a new AbstractSVGList.
131      */
132     protected AbstractSVGList() {
133     }
134                                 
135     /**
136      * Return the number of items in the list.
137      *
138      * @return number of items in the list
139      */
140     public int getNumberOfItems( ){
141 
142         revalidate();
143 
144         if ( itemList != null ){
145             return itemList.size();
146         }
147         else{
148             return 0;
149         }
150     }
151 
152     /**
153      * Clears all existing current items from 
154      * the list, with the result being an empty 
155      * list.
156      * 
157      * @exception DOMException NO_MODIFICATION_ALLOWED_ERR: 
158      *   Raised when the listcannot be modified.
159      */
160     public void clear()
161         throws DOMException   {
162         revalidate();
163         if ( itemList != null ){
164             //set parents to null
165             clear(itemList);
166             //set the DOM attribute
167             resetAttribute();
168         }
169     }
170 
171     /**
172      * Clears all existing current items from 
173      * the list and re-initializes the list to 
174      * hold the single item specified by the 
175      * parameter.
176      *
177      * @param newItem The item which should 
178      *   become the only member of the list.
179      *
180      * @return The item being inserted into the list.
181      *
182      * @exception DOMException NO_MODIFICATION_ALLOWED_ERR: 
183      *   Raised when the list cannot be modified.
184      * @exception SVGException SVG_WRONG_TYPE_ERR: 
185      *   Raised if parameter newItem is the wrong 
186      *   type of object for the given list.
187      */
188     protected SVGItem initializeImpl ( Object   newItem )
189         throws DOMException  , SVGException {
190 
191         checkItemType(newItem);
192         
193         //create the list or clean it
194         if ( itemList == null ) {
195             itemList = new ArrayList  (1);
196         }
197         else{
198             //set the parents to null
199             clear(itemList);
200         }
201 
202         SVGItem item = removeIfNeeded(newItem);
203 
204         //add the item, the list contains nothing.
205         itemList.add(item);
206 
207         //set the parent 
208         item.setParent(this);
209 
210         //update the XML attribute
211         resetAttribute();
212 
213         return( item );
214     }
215 
216     /**
217      * Returns the specified item from the list.
218      *
219      * @param index The index of the item 
220      *   from the list which is to be returned. 
221      *   The first item is number 0.
222      * @return The selected item.
223      *
224      * @exception DOMException INDEX_SIZE_ERR: 
225      *   Raised if the index number is negative or
226      *   greater than or equal to numberOfItems.
227      */
228     protected SVGItem getItemImpl ( int index )
229         throws DOMException   {
230         revalidate();
231 
232         if ( index < 0 || itemList == null || index >= itemList.size() ){
233             throw createDOMException(DOMException.INDEX_SIZE_ERR,
234                     "AbstractSVGList.getItem.OutOfBoundsException",
235                     null);
236         }
237 
238         return (SVGItem)itemList.get(index);
239     }
240 
241     /**
242      * Inserts a new item into the list at 
243      * the specified position. 
244      *
245      * The first item is number 0. If newItem 
246      * is already in a list, it is removed from 
247      * its previous list before it is inserted into
248      * this list.
249      *
250      * @param newItem The item which is to be inserted 
251      *   into the list.
252      * @param index The index of the item before which 
253      *   the new item is to be inserted. The first item 
254      *   is number 0. If the index is equal to 0, then 
255      *   the new item is inserted at the front of the 
256      *   list. If the index is greater than or equal to 
257      *   numberOfItems, then the new item is appended 
258      *   to the end of the list.
259      *
260      * @return The inserted item.
261      *
262      * @exception DOMException NO_MODIFICATION_ALLOWED_ERR: 
263      *   Raised when the list cannot be modified.
264      * @exception SVGException SVG_WRONG_TYPE_ERR: 
265      *   Raised if parameter newItem is the wrong type of 
266      *   object for the given list.
267      */
268     protected SVGItem insertItemBeforeImpl ( Object   newItem, int index )
269         throws DOMException  , SVGException {
270 
271         checkItemType(newItem);
272 
273         revalidate();
274         if ( index < 0 ) {
275             throw createDOMException(DOMException.INDEX_SIZE_ERR,
276                     "AbstractSVGList.insertItemBefore.OutOfBoundsException",
277                     null);
278         }
279         
280         if ( index > itemList.size() ){
281             index = itemList.size();
282         }
283 
284         SVGItem item = removeIfNeeded(newItem);
285 
286         //add the item at its position
287         itemList.add(index,item);
288 
289         //set the parent
290         item.setParent(this);
291 
292         resetAttribute();
293 
294         return( item );
295     }
296 
297 
298     /**
299      * Replaces an existing item in the list with a 
300      * new item. 
301      * If newItem is already in a list, it is removed 
302      * from its previous list before it is inserted 
303      * into this list.
304      *
305      * @param newItem The item which is to be inserted 
306      *   into the list.
307      * @param index The index of the item which is to
308      *   be replaced. The first item is number 0.
309      *
310      * @return The inserted item.
311      *
312      * @exception DOMException NO_MODIFICATION_ALLOWED_ERR: 
313      *   Raised when the list cannot be modified.
314      *                         INDEX_SIZE_ERR: 
315      *   Raised if the index number is negative or greater 
316      *   than or equal to numberOfItems.
317      * @exception SVGException SVG_WRONG_TYPE_ERR: 
318      *   Raised if parameter newItem is the wrong type 
319      *   of object for the given list.
320      */
321     protected SVGItem replaceItemImpl ( Object   newItem, int index )
322         throws DOMException  , SVGException {
323 
324         checkItemType(newItem);
325 
326         revalidate();
327         if ( index < 0 || index >= itemList.size() ){
328             throw createDOMException(DOMException.INDEX_SIZE_ERR,
329                     "AbstractSVGList.replaceItem.OutOfBoundsException",
330                     null);
331         }
332 
333         SVGItem item = removeIfNeeded(newItem);
334 
335         //substitute the item 
336         itemList.set(index,item);
337 
338         //set the parent
339         item.setParent(this);
340 
341         resetAttribute();
342 
343         return( item );
344     }
345     
346     /**
347      * Removes an existing item from the list.
348      *
349      * @param index The index of the item which 
350      *   is to be removed. The first item is number 0.
351      *
352      * @return The removed item.
353      *
354      * @exception DOMException NO_MODIFICATION_ALLOWED_ERR: 
355      *   Raised when the list cannot be modified.
356      *                         INDEX_SIZE_ERR: 
357      *   Raised if the index number is negative or greater 
358      *   than or equal to numberOfItems.
359      */
360     protected SVGItem removeItemImpl ( int index )
361         throws DOMException   {
362 
363         revalidate();
364         if ( index < 0 || index >= itemList.size() ){
365             throw createDOMException(DOMException.INDEX_SIZE_ERR,
366                    "AbstractSVGList.removeItem.OutOfBoundsException",
367                    null);
368         }
369 
370         SVGItem item = (SVGItem)itemList.remove(index);
371         
372         //no parent assign to the item since removed
373         item.setParent(null);
374         
375         resetAttribute();
376 
377         return( item );
378     }
379     
380     /**
381      * Inserts a new item at the end of the list. 
382      * If newItem is already in a list, it is removed from
383      * its previous list before it is inserted into this list.
384      *
385      * @param newItem The item which is to be inserted 
386      *  into the list. The first item is number 0.
387      *
388      * @return The inserted item.
389      *
390      * @exception DOMException NO_MODIFICATION_ALLOWED_ERR: 
391      *   Raised when the list cannot be modified.
392      * @exception SVGException SVG_WRONG_TYPE_ERR: 
393      *   Raised if parameter newItem is the wrong type 
394      *   of object for the given list.
395      */
396     protected SVGItem appendItemImpl ( Object   newItem )
397         throws DOMException  , SVGException {
398 
399         checkItemType(newItem);
400 
401         revalidate();
402 
403         SVGItem item = removeIfNeeded(newItem);
404 
405         itemList.add(item);
406 
407         //set the parent
408         item.setParent(this);
409 
410         if ( itemList.size() <= 1 ){
411             resetAttribute();
412         }
413         else{
414             resetAttribute(item);
415         }
416         
417         return( item );
418     }
419 
420     /**
421      * If the itemis already in another list,
422      * then remove the item from its parent list.
423      * If not, create a proper item for the
424      * object representing the type of item
425      * the list contains
426      *
427      * checkItemItem was preformed previously.
428      *
429      * @param newItem : item to be removed
430      *  from its parent list potentially
431      *
432      * @return item to be inserted in the list.
433      */
434     protected SVGItem removeIfNeeded(Object   newItem){
435 
436         SVGItem item = null;
437 
438         if ( newItem instanceof SVGItem ){
439             //existing item, remove the item
440             // first from its original list
441             item = (SVGItem)newItem;
442             if ( item.getParent() != null ){
443                 item.getParent().removeItem(item);
444             }
445         }
446         else{
447             item = createSVGItem( newItem );
448         }
449 
450         return item;
451     }
452 
453     /**
454      * Initializes the list, if needed.
455      */
456     protected void revalidate() {
457         if (valid) {
458             return;
459         }
460         
461         try{
462             ListBuilder builder = new ListBuilder();
463 
464             doParse(getValueAsString(),builder);
465 
466             if ( builder.getList() != null ){
467                 clear(itemList);
468             }
469             itemList = builder.getList();
470         }
471         catch(ParseException e){
472             itemList = null;
473         }
474         valid = true;
475     }
476 
477     /**
478      * Set the attribute value in the DOM.
479      *
480      * @param value list of item to be used as
481      *   the new attribute value.
482      */
483     protected void setValueAsString(List   value) throws DOMException   {
484 
485         StringBuffer   buf = null;
486         Iterator   it = value.iterator();
487         while( it.hasNext() ){
488             SVGItem item = ( SVGItem )it.next();
489 
490             if ( buf == null ){
491                 buf = new StringBuffer  (item.getValueAsString());
492             }
493             else{
494                 buf.append(getItemSeparator());
495                 buf.append(item.getValueAsString());
496             }
497         }
498         String   finalValue = null;
499         if ( buf == null ){
500             finalValue = null;
501         }
502         else{
503             finalValue = buf.toString();
504         }
505         setAttributeValue(finalValue);
506 
507         valid = true;
508     }
509 
510     /**
511      */
512     public void itemChanged(){
513         resetAttribute();
514     }
515 
516     /**
517      * Resets the value of the associated attribute.
518      */
519     protected void resetAttribute() {
520         setValueAsString(itemList);
521     }
522 
523     /**
524      * Resets the value of the associated attribute.
525      *
526      * @param item : last item appended
527      */
528     protected void resetAttribute(SVGItem item) {
529         StringBuffer   buf = new StringBuffer  (getValueAsString());
530         buf.append(getItemSeparator());
531         buf.append(item.getValueAsString());
532         setAttributeValue(buf.toString());
533         valid = true;
534     }
535 
536     /**
537      * Invalidates this list.
538      */
539     public void invalidate() {
540         valid = false;
541     }
542 
543     /**
544      * Remove an item from the list.
545      *
546      * This operation takes place when an
547      * item was already in one list and 
548      * is being added to another one.
549      *
550      * @param item the item to be removed from 
551      *   this list
552      */
553     protected void removeItem(SVGItem item){
554         if ( itemList.contains(item) ){
555             itemList.remove(item);
556             item.setParent(null);
557             resetAttribute();
558         }
559     } 
560 
561     /**
562      * Clear the list and set the parent 
563      * of the items to null.
564      *
565      * @param list to be cleared
566      */
567     protected void clear(List   list){
568         if ( list == null ){
569             return;
570         }
571 
572         Iterator   it = list.iterator();
573 
574         while( it.hasNext() ){
575             SVGItem item = (SVGItem)it.next();
576             item.setParent(null);
577         }
578 
579         list.clear();
580     }
581 
582     /**
583      * Local list handler implementation.
584      *
585      * This will contructs a list of item coming
586      * out of the parser for the attribute.
587      */
588     protected class ListBuilder implements ListHandler {
589 
590         /**
591          * the list to be build
592          */
593         protected List   list;
594 
595         /// Default constructor.
596         public ListBuilder(){
597         }
598 
599         /**
600          * Return the newly created list.
601          * 
602          * @return the created list
603          */
604         public List   getList(){
605             return list;
606         }
607 
608         public void startList(){
609             if ( list == null ){
610                 list = new ArrayList  ();
611             }
612         }
613 
614         public void item(SVGItem item){
615             item.setParent(AbstractSVGList.this);
616             list.add(item);
617         }
618         
619         public void endList(){
620         }
621     }
622 }
623
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags