com.ibatis.sqlmap.engine.mapping.result.ResultObjectFactory Maven / Gradle / Ivy
/*
* Copyright 2006 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.ibatis.sqlmap.engine.mapping.result;
/**
* iBATIS uses an implementation of this interface to create
* result objects after the execution of a statement. To use, specify
* your implementation class as the type for the "resultObjectFactory"
* element in the SqlMapConfig. Any implementation of this interface
* must have a public no argument constructor.
*
* Note that iBATIS makes use of this interface through the
* ResultObjectFactoryUtil class.
*
* @author Jeff Butler
*
*/
public interface ResultObjectFactory {
/**
* Returns a new instance of the requested class.
* iBATIS will call this method in these circumstances:
*
*
* - When processing a result set - to create new instances of result objects
* - When processing the output parameters of a stored procedure - to create
* instances of OUTPUT parameters
*
* - When processing a nested select - to create instances of parameter
* objects on the nested select
*
* - When processing result maps with nested result maps. iBATIS will
* ask the factory to create an instance of the nested object. If the nested
* object is some implementation of
java.util.Collection
* then iBATIS will supply default implementations of the common interfaces
* if the factory chooses not to create the object. If the
* embedded object is a java.util.List or
* java.util.Collection the default behavior is to
* create an java.util.ArrayList. If the embedded object is a
* java.util.Set the default behavior
* is to create a java.util.HashSet.
*
*
* If you return null from this method, iBATIS will attempt
* to create in instance of the class with it's normal mechanism. This means
* that you can selectively choose which objects to create with this interface.
* In the event that you choose not to create an object, iBATIS will translate some
* common interfaces to their common implementations. If the requested
* class is List or Collection iBATIS will create an ArrayList. If the requested
* class is Set then iBATIS will create a HashSet. But these rules only apply
* if you choose not to create the object. So you can use this factory to
* supply custom implementations of those interfaces if you so desire.
*
* @param statementId the ID of the statement that generated the call to this method
* @param clazz the type of object to create
* @return a new instance of the specified class. The instance must
* be castable to the specified class. If you return null,
* iBATIS will attempt to create the instance using it's normal
* mechanism.
* @throws InstantiationException if the instance cannot be created. If you
* throw this Exception, iBATIS will throw a runtime exception in response and
* will end.
* @throws IllegalAccessException if the constructor cannot be accessed. If you
* throw this Exception, iBATIS will throw a runtime exception in response and
* will end.
*/
Object createInstance(String statementId, Class clazz) throws InstantiationException, IllegalAccessException;
/**
* Called for each property configured in the SqlMapCong file. All the properties
* will be set before any call is made to createInstance
*
* @param name
* @param value
*/
void setProperty(String name, String value);
}