001: /*
002: * Copyright 2004-2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.compass.core.marshall;
018:
019: import org.compass.core.Resource;
020: import org.compass.core.mapping.ResourceMapping;
021:
022: /**
023: * Responsible for marhslling and unmarashlling high level objects (a.k.a root object)
024: * to and from {@link Resource}.
025: *
026: * @author kimchy
027: */
028: public interface MarshallingStrategy {
029:
030: /**
031: * Unmarshalls the given resource to an Object based on the {@link ResourceMapping}
032: * regsitered under the {@link Resource} alias.
033: *
034: * @param resource The resource to unmarshall from
035: * @return The object unmarshalled from the resource
036: */
037: Object unmarshall(Resource resource);
038:
039: /**
040: * Unmarshalls the given resource to an Object based on the {@link ResourceMapping}
041: * regsitered under the {@link Resource} alias WITHIN the given marshalling context.
042: *
043: * @param resource The resource to unmarshall from
044: * @param context The context to unmarshall the resource within
045: * @return The object unmarshalled from the resource
046: */
047: Object unmarshall(Resource resource, MarshallingContext context);
048:
049: /**
050: * Marshalls the given Object into a {@link Resource} based on the {@link ResourceMapping}
051: * associated with the provided alias. Returns <code>null</code> if there are no mappings.
052: *
053: * @param alias The alias to look up the {@link ResourceMapping}
054: * @param root The object to marshall into the resource
055: * @return The resource result of marshalling the object or <code>null</code> if has no mapping
056: */
057: Resource marshall(String alias, Object root);
058:
059: /**
060: * Marshalls the given Object into a {@link Resource} based on the {@link ResourceMapping}
061: * associated with the provided object. If the object implements {@link org.compass.core.spi.AliasedObject},
062: * the alias will be used to look up the {@link ResourceMapping}, otherwise, the object class will be used.
063: *
064: * @param root The object to marshall into a resource
065: * @return The resource result of marshalling the object
066: */
067: Resource marshall(Object root);
068:
069: /**
070: * <p>Marshalls the given id object into a Resource (a resource having only its ids set).
071: * Note, that the id can be several types, depending on the mapping. For example, for
072: * class mapping, it can be the root Object itself (with its ids set), an array of ids,
073: * or if a single id, the actual id object.
074: *
075: * <p>The {@link ResourceMapping} are looked up based on the given object.
076: *
077: * <p>Will return <code>null</code> if no mappins are found
078: *
079: * @param id The id to marshall into a {@link Resource}
080: * @return A resource having its id properties set
081: */
082: Resource marshallIds(Object id);
083:
084: /**
085: * <p>Marshalls the give id object into a Resource (a resource having only its ids set).
086: * Note, that the id can be several types, depending on the mapping. For example, for
087: * class mapping, it can be the root Object itself (with its ids set), an array of ids,
088: * or if a single id, the actual id object.
089: *
090: * <p>The {@link ResourceMapping} are looked up based on the given alias.
091: *
092: * <p>Will return <code>null</code> if no mappins are found
093: *
094: * @param alias The alias to look up the {@link ResourceMapping} based
095: * @param id The id to marshall into a {@link Resource}
096: * @return A resource having its id properties set
097: */
098: Resource marshallIds(String alias, Object id);
099:
100: /**
101: * <p>Marshalls the give id object into a Resource (a resource having only its ids set).
102: * Note, that the id can be several types, depending on the mapping. For example, for
103: * class mapping, it can be the root Object itself (with its ids set), an array of ids,
104: * or if a single id, the actual id object.
105: *
106: * <p>The {@link ResourceMapping} are looked up based on the given class.
107: *
108: * <p>Will return <code>null</code> if no mappins are found
109: *
110: * @param clazz The class to look up the {@link ResourceMapping} based
111: * @param id The id to marshall into a {@link Resource}
112: * @return A resource having its id properties set
113: */
114: Resource marshallIds(Class clazz, Object id);
115:
116: /**
117: * Marshalls the give id object into a Resource (a resource having only its ids set).
118: * Note, that the id can be several types, depending on the mapping. For example, for
119: * class mapping, it can be the root Object itself (with its ids set), an array of ids,
120: * or if a single id, the actual id object.
121: *
122: * @param resourceMapping The resource mapping holding how to marhsall the ids
123: * @param id The id to marshall into a {@link Resource}
124: * @return A resource having its id properties set
125: */
126: Resource marshallIds(ResourceMapping resourceMapping, Object id);
127:
128: /**
129: * Marshalls the give id object into the provided Resource (a resource having only its ids set).
130: * Note, that the id can be several types, depending on the mapping. For example, for
131: * class mapping, it can be the root Object itself (with its ids set), an array of ids,
132: * or if a single id, the actual id object.
133: *
134: * @param resource The resource to marhsll the ids into
135: * @param resourceMapping The resource mapping holding how to marhsall the ids
136: * @param id The id to marshall into a {@link Resource}
137: * @return <code>true</code> if stored properties were added to the {@link Resource}.
138: */
139: boolean marshallIds(Resource resource,
140: ResourceMapping resourceMapping, Object id,
141: MarshallingContext context);
142:
143: /**
144: * Marhsalls the give id into the actual object. Kindda hacky... .
145: *
146: * @param root The object to marshall the ids into
147: * @param id The id to marshall into the root object
148: */
149: void marshallIds(Object root, Object id);
150:
151: /**
152: * Marhsalls the give id into the actual object. Kindda hacky... .
153: *
154: * @param resourceMapping The resource mapping for the given object
155: * @param root The object to marshall the ids into
156: * @param id The id to marshall into the root object
157: */
158: void marshallIds(ResourceMapping resourceMapping, Object root,
159: Object id);
160:
161: /**
162: * Unmarshalls the given id object into an array of all the id values. The results depends
163: * on the type of the mappings (raw resource/class).
164: * <p/>
165: * The unmarshalling is performed based on {@link ResourceMapping} associated with the given
166: * alias.
167: *
168: * @param alias The alias to lookup the {@link ResourceMapping}
169: * @param id The id to unmarshall
170: * @return An array of all the ids
171: */
172: Object[] unmarshallIds(String alias, Object id);
173:
174: /**
175: * Unmarshalls the given id object into an array of all the id values. The results depends
176: * on the type of the mappings (raw resource/class).
177: * <p/>
178: * The unmarshalling is performed based on {@link ResourceMapping} associated with the given
179: * class.
180: *
181: * @param clazz The class to lookup the {@link ResourceMapping}
182: * @param id The id to unmarshall
183: * @return An array of all the ids
184: */
185: Object[] unmarshallIds(Class clazz, Object id);
186:
187: /**
188: * Unmarshalls the given id object into an array of all the id values. The results depends
189: * on the type of the mappings (raw resource/class).
190: * <p/>
191: * The unmarshalling is performed based on {@link ResourceMapping} provided.
192: *
193: * @param resourceMapping The resource to perform the unmarshalling based on
194: * @param id The id to unmarshall
195: * @return An array of all the ids
196: */
197: Object[] unmarshallIds(ResourceMapping resourceMapping, Object id,
198: MarshallingContext context);
199:
200: }
|