| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You 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 flex.messaging.io; |
| |
| import java.util.List; |
| |
| /** |
| * A PropertyProxy allows customized serialization and deserialization of complex objects by |
| * providing access to each of the steps in the serialization and deserialization process. |
| * A serializer asks a PropertyProxy for the class name, traits |
| * and properties during serialization. A deserializer asks a PropertyProxy |
| * to create a new instance and set property values. |
| * <p> |
| * Different PropertyProxy implementations may be written for different |
| * types of objects such as Map, Dictionary, Enumerable, Throwable, |
| * and Beans. |
| */ |
| public interface PropertyProxy extends Cloneable { |
| /** |
| * The default instance managed by this PropertyProxy. The |
| * default instance is used for one-type proxied instances. |
| * |
| * @return The proxied instance. |
| */ |
| Object getDefaultInstance(); |
| |
| /** |
| * Sets the default instance managed by this PropertyProxy. |
| * |
| * @param defaultInstance The default instance. |
| */ |
| void setDefaultInstance(Object defaultInstance); |
| |
| /** |
| * Creates a new instance for the given className. ClassName is the |
| * value of the "alias" for the ActionScript class serialized. |
| * If the className is invalid an anonymous ASObject is created. If the className is |
| * prefixed with ">" an ASObject is created with the type set however |
| * a concrete instance is not instantiated. |
| * |
| * @param className the class to create |
| * @return an instance of className |
| */ |
| Object createInstance(String className); |
| |
| /** |
| * The List of property names as Strings that make up the traits |
| * of the default instance. These traits determine which properties |
| * are to be serialized. |
| * |
| * @return The set of property names as Strings to be serialized. |
| */ |
| List getPropertyNames(); |
| |
| /** |
| * The List of property names as Strings that make up the traits |
| * of the given instance. These traits determine which properties |
| * are to be serialized. |
| * |
| * @param instance the object to examine |
| * @return List of property names as Strings to be serialized. |
| */ |
| List getPropertyNames(Object instance); |
| |
| /** |
| * Looks up the Class type of the property by name on the default instance. |
| * |
| * @param propertyName The name of the property. |
| * @return The property type. |
| */ |
| Class getType(String propertyName); |
| |
| /** |
| * Looks up the Class type of the property by name on the given instance. |
| * |
| * @param instance The instance that possesses the property. |
| * @param propertyName The name of the property. |
| * @return The property type. |
| */ |
| Class getType(Object instance, String propertyName); |
| |
| /** |
| * Looks up the value of the property by name from the default |
| * instance. |
| * |
| * @param propertyName The name of the property. |
| * @return The value of the given property. |
| */ |
| Object getValue(String propertyName); |
| |
| /** |
| * Looks up the value of a property by name for the given instance. |
| * |
| * @param instance The instance that possesses the requested property. |
| * @param propertyName The name of the property. |
| * @return The value of the given property. |
| */ |
| Object getValue(Object instance, String propertyName); |
| |
| /** |
| * Updates the value of a propery by name for the default instance. |
| * |
| * @param propertyName the property name |
| * @param value the new value |
| */ |
| void setValue(String propertyName, Object value); |
| |
| /** |
| * Updates the value of a property by name for the given instance. |
| * |
| * @param instance The instance that possesses the requested property. |
| * @param propertyName The name of the property to update. |
| * @param value The updated value for the property. |
| */ |
| void setValue(Object instance, String propertyName, Object value); |
| |
| /** |
| * This is called after the deserialization of the instance is complete (i.e. |
| * after the lastSetValue call. It has the opportunity to return an instance |
| * to use to replace the instance returned previously in createInstance. |
| * NOTE however that this approach does not support recursive references back to |
| * this same object (i.e. if a property of this object refers back to itself). |
| * |
| * @param instance the instance being deserialized (previously returned from a |
| * createInstance call) |
| * @return possibly the same instance to use for this object. |
| */ |
| Object instanceComplete(Object instance); |
| |
| /** |
| * Allows an alias to be set for the instance type. By default |
| * the classname of the instance is used. |
| * |
| * @param value The class name alias. |
| */ |
| void setAlias(String value); |
| |
| /** |
| * The class name alias for the default instance. |
| * |
| * @return The class name alias to be used in serializing the type traits. |
| */ |
| String getAlias(); |
| |
| /** |
| * The class name alias for the given instance. |
| * |
| * @param instance the object to get the alias of. |
| * @return The class name alias to be used in serializing the type traits. |
| */ |
| String getAlias(Object instance); |
| |
| /** |
| * Dynamic is a client-only concept for types that allow for arbitrary |
| * public properties to be defined at runtime. This setting isn't yet |
| * relevant for serialization but can still be set in the Object traits. |
| * |
| * @param value Whether the client type is expected to be dynamic. This setting |
| * is currently not used. |
| */ |
| void setDynamic(boolean value); |
| |
| /** |
| * The trait setting "dynamic" is a client-only concept for types that |
| * allow for arbitrary public properties to be defined at runtime. |
| * The default is false and it is unlikely that it would need to be set. |
| * |
| * @return The dynamic client trait setting to be used during serialization of the type. |
| */ |
| boolean isDynamic(); |
| |
| /** |
| * Specifies whether the default instance manages its own serialization through the |
| * Externalizable interface. |
| * |
| * @return Whether the default instance implements java.io.Externalizable. |
| */ |
| boolean isExternalizable(); |
| |
| /** |
| * Specifies whether the given instance manages its own serialization through the |
| * Externalizable interface. |
| * |
| * @param instance the object to check |
| * @return Whether the given instance implements java.io.Externalizable. |
| */ |
| boolean isExternalizable(Object instance); |
| |
| /** |
| * Specifies whether the given instance manages its own serialization through the |
| * Externalizable interface. If this property is set to true then the type |
| * must implement java.io.Externalizable. Setting this property to false allows an |
| * otherwise Externalizable instance to be considered as a normal type for |
| * custom serialization. |
| * |
| * @param value if set to true the instance must implement java.io.Externalizable, otherwise |
| * if set to false the proxied type can avoid external serialization |
| * for an otherwise Externalizable type. |
| */ |
| void setExternalizable(boolean value); |
| |
| /** |
| * The context holds settings that govern serialization behavior. |
| * |
| * @return The current serialization context, or a new default instance if undefined. |
| */ |
| SerializationContext getSerializationContext(); |
| |
| /** |
| * Sets the context for serialization behavior. |
| * |
| * @param value the new context |
| */ |
| void setSerializationContext(SerializationContext value); |
| |
| /** |
| * If set to true, read only properties will be included |
| * during default serialization. The default is false. |
| * |
| * @param value whether read only properties should be included. |
| */ |
| void setIncludeReadOnly(boolean value); |
| |
| /** |
| * Determines whether read only properties from the instance should be included |
| * during default serialization. The default is false. |
| * |
| * @return Whether read only properties should be included during default |
| * serialization. |
| */ |
| boolean getIncludeReadOnly(); |
| |
| /** |
| * A serialization descriptor that provides overrides to the |
| * default behavior for selecting properties for serialization. At |
| * any given level a list of includes and excludes can be specified. |
| * Complex child properties can have their own descriptors specified |
| * in a nested manner. |
| * |
| * @return The serialization descriptor for custom serialization. |
| */ |
| SerializationDescriptor getDescriptor(); |
| |
| /** |
| * Allows non-default inclusion/exclusion of properties for |
| * serialization. |
| * |
| * @param descriptor The descriptor to customize property selection for serialization. |
| */ |
| void setDescriptor(SerializationDescriptor descriptor); |
| |
| /** |
| * Returns a copy of the PropertyProxy so that it can be used as a template without |
| * modifying/creating global references to instances, descriptors etc. |
| * |
| * @return A copy of the PropertyProxy. |
| */ |
| Object clone(); |
| |
| /** |
| * This is called right before we are about to serialize the supplied instance. |
| * You can override this method to serialize an instance which you want to serialize |
| * instead of the instance encountered in the object graph. If you return an |
| * instance of a different class, we use the PropertyProxyRegistry to get a new |
| * proxy for that instance. That proxy is then used during the rest of the serialization. |
| * Note that the objects returned from this method should be serialized through their |
| * properties. You cannot return a String, Integer or other primitive type. |
| * |
| * @param instance the instance encountered during AMF serialization |
| * @return the instance you want to serialize in its place |
| */ |
| Object getInstanceToSerialize(Object instance); |
| } |