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