01: /*
02: * Copyright 2006 The Apache Software Foundation
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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.ibatis.sqlmap.engine.mapping.result;
17:
18: /**
19: * iBATIS uses an implementation of this interface to create
20: * result objects after the execution of a statement. To use, specify
21: * your implementation class as the type for the "resultObjectFactory"
22: * element in the SqlMapConfig. Any implementation of this interface
23: * must have a public no argument constructor.
24: *
25: * Note that iBATIS makes use of this interface through the
26: * ResultObjectFactoryUtil class.
27: *
28: * @author Jeff Butler
29: *
30: */
31: public interface ResultObjectFactory {
32:
33: /**
34: * Returns a new instance of the requested class.
35: * iBATIS will call this method in these circumstances:
36: *
37: * <ul>
38: * <li>When processing a result set - to create new instances of result objects</li>
39: * <li>When processing the output parameters of a stored procedure - to create
40: * instances of OUTPUT parameters
41: * </li>
42: * <li>When processing a nested select - to create instances of parameter
43: * objects on the nested select
44: * </li>
45: * <li>When processing result maps with nested result maps. iBATIS will
46: * ask the factory to create an instance of the nested object. If the nested
47: * object is some implementation of <code>java.util.Collection</code>
48: * then iBATIS will supply default implementations of the common interfaces
49: * if the factory chooses not to create the object. If the
50: * embedded object is a <code>java.util.List</code> or
51: * <code>java.util.Collection</code> the default behavior is to
52: * create an <code>java.util.ArrayList</code>. If the embedded object is a
53: * <code>java.util.Set</code> the default behavior
54: * is to create a <code>java.util.HashSet</code>.</li>
55: * </ul>
56: *
57: * If you return <code>null</code> from this method, iBATIS will attempt
58: * to create in instance of the class with it's normal mechanism. This means
59: * that you can selectively choose which objects to create with this interface.
60: * In the event that you choose not to create an object, iBATIS will translate some
61: * common interfaces to their common implementations. If the requested
62: * class is List or Collection iBATIS will create an ArrayList. If the requested
63: * class is Set then iBATIS will create a HashSet. But these rules only apply
64: * if you choose not to create the object. So you can use this factory to
65: * supply custom implementations of those interfaces if you so desire.
66: *
67: * @param statementId the ID of the statement that generated the call to this method
68: * @param clazz the type of object to create
69: * @return a new instance of the specified class. The instance must
70: * be castable to the specified class. If you return <code>null</code>,
71: * iBATIS will attempt to create the instance using it's normal
72: * mechanism.
73: * @throws InstantiationException if the instance cannot be created. If you
74: * throw this Exception, iBATIS will throw a runtime exception in response and
75: * will end.
76: * @throws IllegalAccessException if the constructor cannot be accessed. If you
77: * throw this Exception, iBATIS will throw a runtime exception in response and
78: * will end.
79: */
80: Object createInstance(String statementId, Class clazz)
81: throws InstantiationException, IllegalAccessException;
82:
83: /**
84: * Called for each property configured in the SqlMapCong file. All the properties
85: * will be set before any call is made to createInstance
86: *
87: * @param name
88: * @param value
89: */
90: void setProperty(String name, String value);
91: }
|