# @(#)CHANGES.txt 1.4 11/13/00 Created: 9 October 2000 JAI 1.1 Specification Changes Since Community Review ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------- 10/17/2000, aastha RemoteJAI: 1. Docs for getServerName now have the word "String" enclosed in tags. 2. New class comments added at line 93: * When a new RemoteJAI instance is * constructed, its hints are initialized to a copy of the default * hints. Thus when an instance of RemoteJAI is * constructed, hints for the default registry, tile cache, number of * retries, and the retry interval are added to the set of common * rendering hints. Similarly, invoking setOperationRegistry(), * setTileCache(), setNumRetries() or * setRetryInterval() on a RemoteJAI instance * will cause the respective entity to be added to the common rendering * hints. 3. The following RenderingHints.Key static variables were moved from RemoteJAI into JAI, as JAI is the central repository for these statics : KEY_RETRY_INTERVAL, KEY_NUM_RETRIES, and KEY_NEGOTIATION_PREFERENCES 4. Following added to the comments for the setRetryInterval() method: * The * specified retryInterval parameter will be added * to the common RenderingHints of this * RemoteJAI instance, under the * JAI.KEY_RETRY_INTERVAL key. 5. Following added to the comments for the setNumRetries() method: * The specified numRetries * parameter will be added to the common RenderingHints * of this RemoteJAI instance, under the * JAI.KEY_NUM_RETRIES key. 6. The getNegotiatedValues(String category) method is now documented to throw an IllegalArgumentException if category is null. 7. The following was added to the method comments for the getServerCapabilities() method: * If any * network related errors are encountered by this method (identified * as such by receiving a RemoteImagingException), they * will be dealt with by the use of retries and retry intervals. 8. The following was added to the method comments for the getServerSupportedOperationList() method: * If any * network related errors are encountered by this method (identified * as such by receiving a RemoteImagingException), they * will be dealt with by the use of retries and retry intervals. 9. Removed the following line from the following method documentations: both constructors : @throws IllegalArgumentException if serverName is null. Added the following comments to the following methods: both constructors : *

An IllegalArgumentException may * be thrown by the protocol specific classes at a later point, if * null is provided as the serverName argument and null is not * considered a valid server name by the specified protocol. RemoteImagingException: 1. Put tags around "RemoteImagingException" and "String" words in comments for both constructors. RemoteDescriptor: 1. Added @param statements for serverName argument to the getServerSupportedOperationList() and getServerCapabilities() methods. 2. Added the following comments to both the above mentioned methods: * The format of the serverName argument is protocol-dependent. Thus * different protocol specific subclasses may treat the same * serverName argument in different ways, i.e. one protocol may allow * the serverName argument to be null (if this protocol defines a * default server), while another may consider null an invalid * serverName and throw an Exception. RemoteDescriptorImpl: 1. Changed the name of the argument from registryModeName to modeName in accordance with naming in RegistryElementDescriptor. Added the following to the method docs for getSupportedModes() : * * @param modeName The mode name to check support for. * * @return true, if the implementation of this descriptor supports * the specified mode. false otherwise. * * @throws IllegalArgumentException if modeName is null 2. Added @param statements for the modeName argument to the getPropertyGenerators() and getParameterListDescriptor() methods. JAIRMIDescriptor: 1. Added the following comments to the method documentation for the getServerSupportedOperationList and getServerCapabilities methods: *

If the supplied serverName argument is null, then the local * host will be used instead. Also removed the following from both these methods: @throws IllegalArgumentException if serverName is null. 2. The following added to the class documentation: *

If the serverName supplied to any "jairmi" protocol implementing * class's method is null, then the local host will be used instead. RemoteRIF/RemoteCRIF: 1. Removed all the @throws documentation statements. The reason for this is that this is asymmetrical with the local JAI chain of execution. The only place where any validation/checking of parameters is supposed to take place is within JAI.create. The RenderedImageFactory interface's create method is not defined to do any parameter validations, since these are generally already done by JAI.create. If a user happens to call a RIF.create() directly (this method not being called as a result of a JAI.create()), then the user is responsible for the validity of the parameters. Since remote chain of execution is symmetrical to the local one in most cases, it should be consistent here too. Thus all parameter validation is done through RemoteJAI.create and none should be specified at RemoteRIF.create time. Similar considerations apply to RemoteCRIF. All @throws from any method on RemoteCRIF have also been removed for symmetry with ContextualRenderedImageFactory and local JAI renderable chain of execution. 2. Since most methods in RemoteRIF will require some network communication with the server, the following methods now throw RemoteImagingException: RemoteRIF: create() RemoteCRIF: mapRenderContext(), create(), getBounds2D(), getPropertyNames(), isDynamic() RemoteRenderedOp: 1. Removed the following line from the following method documentations: both constructors : @throws IllegalArgumentException if serverName is null. Added the following comments to the following methods: both constructors : *

An IllegalArgumentException may * be thrown by the protocol specific classes at a later point, if * null is provided as the serverName argument and null is not * considered a valid server name by the specified protocol. RemoteRenderableOp: 1. Removed the following line from the following method documentations: both constructors : @throws IllegalArgumentException if serverName is null. Added the following comments to the following methods: both constructors : *

An IllegalArgumentException may * be thrown by the protocol specific classes at a later point, if * null is provided as the serverName argument and null is not * considered a valid server name by the specified protocol. PlanarImageServerProxy: 1. Removed the following line from the following method documentations: constructor : @throws IllegalArgumentException if serverName is null. Added the following comments to the following methods: constructor : *

An IllegalArgumentException may * be thrown by the protocol specific classes at a later point, if * null is provided as the serverName argument and null is not * considered a valid server name by the specified protocol. Negotiable: 1. Following comments added to the method documentation for the negotiate(Negotiable) method: *

If NO_PARAMETER_VALUE is supplied as an argument * to this method, the negotiation will fail and * NO_PARAMETER_VALUE will be returned to signify the * failure of the negotiation. 2. Following comments * If the supplied Negotiable * is null, then this Negotiable is returned as is from * this method. replaced with *

If the supplied argument is null, an * IllegalArgumentException will be thrown, as it is not * possible to negotiate with a null value. For the same reason, * null is not a valid value to return as the negotiated result * from this method. It may, however, be noted * that it is valid for getNegotiatedValue() to return * null, i.e the single value result of the negotiation can be null. -------------------- 10/19/2000 Replaced the NegotiableEnumeration class with the NegotiableCollection class, the API definition for which is as follows: package javax.media.jai.remote; /** * A class that wraps an Collection to implement the * Negotiable interface. NegotiableCollection * is a convenience class to specify a Negotiable value for * a parameter whose valid values are contained in an Collection. * * @since 1.1 */ public class NegotiableCollection implements Negotiable { /** * Creates a NegotiableCollection given an * Collection. * * @throws IllegalArgumentException if collection is null. * @throws IllegalArgumentException if all the elements of collection * are not of the same Class type. */ public NegotiableCollection(Collection collection) {} /** * Creates a NegotiableCollection given an array of * Objects. The elements of the Object * array are treated as being the elements of an Collection. * * @throws IllegalArgumentException if objects is null. * @throws IllegalArgumentException if all the elements of objects are not * of the same Class type. */ public NegotiableCollection(Object objects[]) {} /** * Returns the Collection of values which are currently * valid for this class, null if there are no valid values. */ public Collection getCollection() {} /** * Returns a NegotiableCollection that contains those * elements that are common to this NegotiableCollection * and the one supplied. If the supplied Negotiable is not * a NegotiableCollection with its elements being of the * same Class as this class', or if there are no common * elements, the negotiation will fail and * Negotiable.NO_PARAMETER_VALUE (signifying * the failure of the negotiation) will be returned. * * @param other The Negotiable to negotiate with. * @throws IllegalArgumentException if other is null. */ public Negotiable negotiate(Negotiable other) {} /** * Returns a single value that is valid for this * NegotiableCollection. The returned value is the first * element contained in this NegotiableCollection. Returns * Negotiable.NO_PARAMETER_VALUE * if there are no valid elements in this NegotiableCollection. */ public Object getNegotiatedValue() {} /** * Returns the Class of the Object returned as the result * of the negotiation. */ public Class getNegotiatedValueClass() {} } -------------------- JAI OperationRegistry Modification Proposal ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Changes since community review inception Krishna - removed package scope "static ... initializeRegistry()" from OperationRegistry since it is not relevant to the public proposal. - The OR constructor is no longer thread-safe. Added a new method "getThreadSafeOperationRegistry" which returns a thread-safe wrapped version of OR. - "registerServices" in OR now throws an IOException and has updated docs. - throw IllegalArgumentException instead of NullPointerException whenever arguments are null. - made ParameterListImpl implement Serializable Documentation update/clarifications : OperationRegistry - initializeFromStream, updateFromStream, readExternal, writeExternal - removed "synchronized" keyword from deprecated methods "suppressAllProperties" and "clearOperationPreferences" - minor class comments correction. JAI - update docs for getDefaultInstance & getOperationRegistry to clarify thread-safety of OR OperationDescriptorImpl - added a warning on use of deprecated constructors to the following methods . getPropertyGenerators(String) . validateSources(String, ParameterBlock, StringBuffer) . getDestClass(String) RED - minor modification to getParameterListDescriptor doc. --------------------