001/*
002 * Registry.java January 2010
003 *
004 * Copyright (C) 2010, Niall Gallagher <niallg@users.sf.net>
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
015 * implied. See the License for the specific language governing 
016 * permissions and limitations under the License.
017 */
018
019package org.simpleframework.xml.convert;
020
021import org.simpleframework.xml.util.Cache;
022import org.simpleframework.xml.util.ConcurrentCache;
023
024/**
025 * The <code>Registry</code> represents an object that is used to
026 * register bindings between a class and a converter implementation.
027 * Converter instances created by this registry are lazily created
028 * and cached so that they are instantiated only once. This ensures 
029 * that the overhead of serialization is reduced. 
030 * 
031 * @author Niall Gallagher
032 * 
033 * @see org.simpleframework.xml.convert.RegistryStrategy
034 */
035public class Registry {
036   
037   /**
038    * This is used to cache the converters based on object types.
039    */
040   private final Cache<Converter> cache;
041   
042   /**
043    * This is used to bind converter types to serializable types.
044    */
045   private final RegistryBinder binder;
046   
047   /**
048    * Constructor for the <code>Registry</code> object. This is used
049    * to create a registry between classes and the converters that
050    * should be used to serialize and deserialize the instances. All
051    * converters are instantiated once and cached for reuse.
052    */
053   public Registry() {
054      this.cache = new ConcurrentCache<Converter>();
055      this.binder = new RegistryBinder();
056   }
057   
058   /**
059    * This is used to acquire a <code>Converter</code> instance from
060    * the registry. All instances are cache to reduce the overhead
061    * of lookups during the serialization process. Converters are
062    * lazily instantiated and so are only created if demanded.
063    * 
064    * @param type this is the type to find the converter for
065    * 
066    * @return this returns the converter instance for the type
067    */
068   public Converter lookup(Class type) throws Exception {
069      Converter converter = cache.fetch(type);
070      
071      if(converter == null) {
072         return create(type);
073      }
074      return converter;
075   }
076   
077   /**
078    * This is used to acquire a <code>Converter</code> instance from
079    * the registry. All instances are cached to reduce the overhead
080    * of lookups during the serialization process. Converters are
081    * lazily instantiated and so are only created if demanded.
082    * 
083    * @param type this is the type to find the converter for
084    * 
085    * @return this returns the converter instance for the type
086    */
087   private Converter create(Class type) throws Exception {
088      Converter converter = binder.lookup(type);
089      
090      if(converter != null) {
091         cache.cache(type, converter);
092      }
093      return converter;
094   }
095   
096   /**
097    * This is used to register a binding between a type and the
098    * converter used to serialize and deserialize it. During the
099    * serialization process the converters are retrieved and 
100    * used to convert the object members to XML.
101    * 
102    * @param type this is the object type to bind to a converter
103    * @param converter this is the converter class to be used
104    * 
105    * @return this will return this registry instance to use
106    */
107   public Registry bind(Class type, Class converter) throws Exception {
108      if(type != null) {
109         binder.bind(type, converter);
110      }
111      return this;
112   }
113   
114   /**
115    * This is used to register a binding between a type and the
116    * converter used to serialize and deserialize it. During the
117    * serialization process the converters are retrieved and 
118    * used to convert the object properties to XML.
119    * 
120    * @param type this is the object type to bind to a converter
121    * @param converter this is the converter instance to be used
122    * 
123    * @return this will return this registry instance to use
124    */
125   public Registry bind(Class type, Converter converter) throws Exception {
126      if(type != null) {
127         cache.cache(type, converter);
128      }
129      return this;
130   }
131}