View Javadoc

1   /*
2    *  Copyright 2001-2013 Stephen Colebourne
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 org.joda.beans;
17  
18  import java.util.Map;
19  import java.util.NoSuchElementException;
20  
21  /**
22   * A meta-bean, defining those aspects of a bean which are not specific
23   * to a particular instance, such as the type and set of meta-properties.
24   * 
25   * @author Stephen Colebourne
26   */
27  public interface MetaBean {
28  
29      /**
30       * Creates a bean builder that can be used to create an instance of this bean.
31       * 
32       * @return the bean builder, not null
33       * @throws UnsupportedOperationException if the bean cannot be created
34       */
35      BeanBuilder<? extends Bean> builder();
36  
37      /**
38       * Creates a map of properties for the specified bean.
39       * 
40       * @param bean  the bean to create the map for, not null
41       * @return the created property map, not null
42       */
43      PropertyMap createPropertyMap(Bean bean);
44  
45      //-----------------------------------------------------------------------
46      /**
47       * Gets the bean name, which is normally the fully qualified class name of the bean.
48       * 
49       * @return the name of the bean, not empty
50       */
51      String beanName();
52  
53      /**
54       * Get the type of the bean represented as a {@code Class}.
55       * 
56       * @return the type of the bean, not null
57       */
58      Class<? extends Bean> beanType();
59  
60      //-----------------------------------------------------------------------
61      /**
62       * Counts the number of properties.
63       * 
64       * @return the number of properties
65       */
66      int metaPropertyCount();
67  
68      /**
69       * Checks if a property exists.
70       * 
71       * @param propertyName  the property name to check, null returns false
72       * @return true if the property exists
73       */
74      boolean metaPropertyExists(String propertyName);
75  
76      /**
77       * Gets a meta-property by name.
78       * 
79       * @param <R>  the property type, optional, enabling auto-casting
80       * @param propertyName  the property name to retrieve, null throws NoSuchElementException
81       * @return the meta property, not null
82       * @throws NoSuchElementException if the property name is invalid
83       */
84      <R> MetaProperty<R> metaProperty(String propertyName);
85  
86      /**
87       * Gets an iterator of meta-properties.
88       * <p>
89       * This method returns an {@code Iterable}, which is simpler than a {@code Map}.
90       * As a result, implementations may be able to optimise, and so this method should be
91       * preferred to {@link #metaPropertyMap()} where a choice is possible.
92       * 
93       * @return the unmodifiable map of meta property objects, not null
94       */
95      Iterable<MetaProperty<?>> metaPropertyIterable();
96  
97      /**
98       * Gets the map of meta-properties, keyed by property name.
99       * <p>
100      * Where possible, use {@link #metaPropertyIterable()} instead.
101      * 
102      * @return the unmodifiable map of meta property objects, not null
103      */
104     Map<String, MetaProperty<?>> metaPropertyMap();
105 
106 }