001: /*
002: * Copyright (C) 2005, 2006 Joe Walnes.
003: * Copyright (C) 2006, 2007, 2008 XStream Committers.
004: * All rights reserved.
005: *
006: * The software in this package is published under the terms of the BSD
007: * style license a copy of which has been included with this distribution in
008: * the LICENSE.txt file.
009: *
010: * Created on 22. January 2005 by Joe Walnes
011: */
012: package com.thoughtworks.xstream.mapper;
013:
014: import com.thoughtworks.xstream.converters.Converter;
015: import com.thoughtworks.xstream.converters.SingleValueConverter;
016:
017: public interface Mapper {
018: /**
019: * Place holder type used for null values.
020: */
021: class Null {
022: }
023:
024: /**
025: * How a class name should be represented in its serialized form.
026: */
027: String serializedClass(Class type);
028:
029: /**
030: * How a serialized class representation should be mapped back to a real class.
031: */
032: Class realClass(String elementName);
033:
034: /**
035: * How a class member should be represented in its serialized form.
036: */
037: String serializedMember(Class type, String memberName);
038:
039: /**
040: * How a serialized member representation should be mapped back to a real member.
041: */
042: String realMember(Class type, String serialized);
043:
044: /**
045: * Whether this type is a simple immutable value (int, boolean, String, URL, etc.
046: * Immutable types will be repeatedly written in the serialized stream, instead of using object references.
047: */
048: boolean isImmutableValueType(Class type);
049:
050: Class defaultImplementationOf(Class type);
051:
052: /**
053: * @deprecated since 1.2, use aliasForAttribute instead.
054: */
055: String attributeForImplementationClass();
056:
057: /**
058: * @deprecated since 1.2, use aliasForAttribute instead.
059: */
060: String attributeForClassDefiningField();
061:
062: /**
063: * @deprecated since 1.2, use aliasForAttribute instead.
064: */
065: String attributeForReadResolveField();
066:
067: /**
068: * @deprecated since 1.2, use aliasForAttribute instead.
069: */
070: String attributeForEnumType();
071:
072: /**
073: * Get the alias for an attrbute's name.
074: *
075: * @param attribute the attribute
076: * @return the alias
077: * @since 1.2
078: */
079: String aliasForAttribute(String attribute);
080:
081: /**
082: * Get the attribut's name for an alias.
083: *
084: * @param alias the alias
085: * @return the attribute's name
086: * @since 1.2
087: */
088: String attributeForAlias(String alias);
089:
090: /**
091: * Get the name of the field that acts as the default collection for an object, or return null if there is none.
092: *
093: * @param definedIn owning type
094: * @param itemType item type
095: * @param itemFieldName optional item element name
096: */
097: String getFieldNameForItemTypeAndName(Class definedIn,
098: Class itemType, String itemFieldName);
099:
100: Class getItemTypeForItemFieldName(Class definedIn,
101: String itemFieldName);
102:
103: ImplicitCollectionMapping getImplicitCollectionDefForFieldName(
104: Class itemType, String fieldName);
105:
106: /**
107: * Determine whether a specific member should be serialized.
108: *
109: * @since 1.1.3
110: */
111: boolean shouldSerializeMember(Class definedIn, String fieldName);
112:
113: interface ImplicitCollectionMapping {
114: String getFieldName();
115:
116: String getItemFieldName();
117:
118: Class getItemType();
119: }
120:
121: /**
122: * @deprecated since 1.3, use {@link #getConverterFromItemType(String, Class, Class)}
123: */
124: SingleValueConverter getConverterFromItemType(String fieldName,
125: Class type);
126:
127: /**
128: * @deprecated since 1.3, use {@link #getConverterFromItemType(String, Class, Class)}
129: */
130: SingleValueConverter getConverterFromItemType(Class type);
131:
132: /**
133: * @deprecated since 1.3, use {@link #getConverterFromAttribute(Class, String)}
134: */
135: SingleValueConverter getConverterFromAttribute(String name);
136:
137: Converter getLocalConverter(Class definedIn, String fieldName);
138:
139: Mapper lookupMapperOfType(Class type);
140:
141: /**
142: * Returns a single value converter to be used in a specific field.
143: *
144: * @param fieldName the field name
145: * @param type the field type
146: * @param definedIn the type which defines this field
147: * @return a SingleValueConverter or null if there no such converter should be used for this
148: * field.
149: * @since 1.2.2
150: */
151: SingleValueConverter getConverterFromItemType(String fieldName,
152: Class type, Class definedIn);
153:
154: /**
155: * Returns an alias for a single field defined in an specific type.
156: *
157: * @param definedIn the type where the field was defined
158: * @param fieldName the field name
159: * @return the alias for this field or its own name if no alias was defined
160: * @since 1.2.2
161: * @deprecated since 1.3, use combination of {@link #serializedMember(Class, String)} and {@link #getConverterFromItemType(String, Class, Class)}
162: */
163: String aliasForAttribute(Class definedIn, String fieldName);
164:
165: /**
166: * Returns the field name for an aliased attribute.
167: *
168: * @param definedIn the type where the field was defined
169: * @param alias the alias
170: * @return the original attribute name
171: * @since 1.2.2
172: * @deprecated since 1.3, use combination of {@link #realMember(Class, String)} and {@link #getConverterFromItemType(String, Class, Class)}
173: */
174: String attributeForAlias(Class definedIn, String alias);
175:
176: /**
177: * Returns which converter to use for an specific attribute in a type.
178: *
179: * @param definedIn the field's parent
180: * @param attribute the attribute name
181: * @since 1.2.2
182: */
183: SingleValueConverter getConverterFromAttribute(Class definedIn,
184: String attribute);
185: }
|