001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. 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,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package org.apache.openjpa.jdbc.meta;
020:
021: import java.io.Serializable;
022: import java.sql.SQLException;
023:
024: import org.apache.openjpa.jdbc.kernel.JDBCFetchConfiguration;
025: import org.apache.openjpa.jdbc.kernel.JDBCStore;
026: import org.apache.openjpa.jdbc.schema.Column;
027: import org.apache.openjpa.jdbc.schema.ColumnIO;
028: import org.apache.openjpa.jdbc.sql.Result;
029: import org.apache.openjpa.kernel.OpenJPAStateManager;
030:
031: /**
032: * Maps a value to a relational schema. Value handler are stateless.
033: *
034: * @author Abe White
035: * @since 0.4.0
036: */
037: public interface ValueHandler extends Serializable {
038:
039: /**
040: * Map the given value and return all mapped columns, or simply return an
041: * array of unmapped default columns. The columns should have at least
042: * their <code>Name</code> and <code>JavaType</code> properties set.
043: *
044: * @param name use as a base to form column name(s); the column names
045: * of unmapped columns will automatically be made to fit
046: * database limitations
047: * @param io I/O information about mapped columns; you do not
048: * have to set this information if returning templates
049: * @param adapt whether to adapt the mapping or schema
050: */
051: public Column[] map(ValueMapping vm, String name, ColumnIO io,
052: boolean adapt);
053:
054: /**
055: * Return whether the values managed by this handler can be used in
056: * state image versioning.
057: */
058: public boolean isVersionable(ValueMapping vm);
059:
060: /**
061: * Return whether this handler potentially must load extra data to extract
062: * the object value from its datastore representation.
063: */
064: public boolean objectValueRequiresLoad(ValueMapping vm);
065:
066: /**
067: * Return the argument to pass to the result set when loading data
068: * via {@link Result#getObject}, or null if none. If this value
069: * occupies multiple columns, return an array with one element per
070: * column. You may return null if all array elements would be null.
071: */
072: public Object getResultArgument(ValueMapping vm);
073:
074: /**
075: * Translate the given value to its datastore equivalent. If this value
076: * occupies multiple columns, return an object array with one element
077: * per column. For relation id columns, return the state manager
078: * the column depends on.
079: */
080: public Object toDataStoreValue(ValueMapping vm, Object val,
081: JDBCStore store);
082:
083: /**
084: * Translate the given datastore value into its Java equivalent. If
085: * the value occupies multiple columns, the given object will be an object
086: * array with one entry per column. This method is only called if
087: * {@link #objectValueRequiresLoad} returns false.
088: */
089: public Object toObjectValue(ValueMapping vm, Object val);
090:
091: /**
092: * Translate the given datastore value into its Java equivalent. If
093: * the value occupies multiple columns, the given object will be an object
094: * array with one entry per column. This method is only called if
095: * {@link #objectValueRequiresLoad} returns true.
096: *
097: * @param sm the state manager that owns the value; may be null if
098: * loading a projection
099: */
100: public Object toObjectValue(ValueMapping vm, Object val,
101: OpenJPAStateManager sm, JDBCStore store,
102: JDBCFetchConfiguration fetch) throws SQLException;
103: }
|