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    
020    package javax.xml.rpc.encoding;
021    
022    /**
023     * The interface <code>javax.xml.rpc.encoding.TypeMappingRegistry</code>
024     * defines a registry of TypeMapping instances for various encoding
025     * styles.
026     *
027     * @version $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $
028     */
029    public interface TypeMappingRegistry extends java.io.Serializable {
030    
031        /**
032         * Registers a <code>TypeMapping</code> instance with the
033         * <code>TypeMappingRegistry</code>. This method replaces any
034         * existing registered <code>TypeMapping</code> instance for
035         * the specified <code>encodingStyleURI</code>.
036         *
037         * @param encodingStyleURI An encoding style specified as an URI.
038         *             An example is "http://schemas.xmlsoap.org/soap/encoding/"
039         * @param mapping TypeMapping instance
040         *
041         * @return Previous TypeMapping associated with the specified
042         *     <code>encodingStyleURI</code>, or <code>null</code>
043         *     if there was no TypeMapping associated with the specified
044         *     <code>encodingStyleURI</code>
045         *
046         * @throws javax.xml.rpc.JAXRPCException if there is any error that prevents
047         *              the registration of the <code>TypeMapping</code> for
048         *              the specified <code>encodingStyleURI</code>
049         */
050        public TypeMapping register(String encodingStyleURI, TypeMapping mapping);
051    
052        /**
053         * Registers the <code>TypeMapping</code> instance that is default
054         * for all encoding styles supported by the
055         * <code>TypeMappingRegistry</code>. A default <code>TypeMapping</code>
056         * should include serializers and deserializers that are independent
057         * of and usable with any encoding style. Successive invocations
058         * of the <code>registerDefault</code> method replace any existing
059         * default <code>TypeMapping</code> instance.
060         * <p>
061         * If the default <code>TypeMapping</code> is registered, any
062         * other TypeMapping instances registered through the
063         * <code>TypeMappingRegistry.register</code> method (for a set
064         * of encodingStyle URIs) override the default <code>TypeMapping</code>.
065         *
066         * @param mapping TypeMapping instance
067         *
068         * @throws javax.xml.rpc.JAXRPCException if there is any error that
069         *              prevents the registration of the default
070         *              <code>TypeMapping</code>
071         */
072        public void registerDefault(TypeMapping mapping);
073    
074        /**
075         * Gets the registered default <code>TypeMapping</code> instance.
076         * This method returns <code>null</code> if there is no registered
077         * default TypeMapping in the registry.
078         *
079         * @return The registered default <code>TypeMapping</code> instance
080         *     or <code>null</code>
081         */
082        public TypeMapping getDefaultTypeMapping();
083    
084        /**
085         * Returns a list of registered encodingStyle URIs in this
086         * <code>TypeMappingRegistry</code> instance.
087         *
088         * @return Array of the registered encodingStyle URIs
089         */
090        public String[] getRegisteredEncodingStyleURIs();
091    
092        /**
093         * Returns the registered <code>TypeMapping</code> for the specified
094         * encodingStyle URI. If there is no registered <code>TypeMapping</code>
095         * for the specified <code>encodingStyleURI</code>, this method
096         * returns <code>null</code>.
097         *
098         * @param encodingStyleURI Encoding style specified as an URI
099         * @return TypeMapping for the specified encodingStyleURI or
100         *     <code>null</code>
101         */
102        public TypeMapping getTypeMapping(String encodingStyleURI);
103    
104        /**
105         * Creates a new empty <code>TypeMapping</code> object.
106         *
107         * @return TypeMapping instance.
108         */
109        public TypeMapping createTypeMapping();
110    
111        /**
112         * Unregisters a TypeMapping instance, if present, from the specified
113         * encodingStyleURI.
114         *
115         * @param encodingStyleURI Encoding style specified as an URI
116         * @return <code>TypeMapping</code> instance that has been unregistered
117         *     or <code>null</code> if there was no TypeMapping
118         *     registered for the specified <code>encodingStyleURI</code>
119         */
120        public TypeMapping unregisterTypeMapping(String encodingStyleURI);
121    
122        /**
123         * Removes a <code>TypeMapping</code> from the TypeMappingRegistry. A
124         * <code>TypeMapping</code> is associated with 1 or more
125         * encodingStyleURIs. This method unregisters the specified
126         * <code>TypeMapping</code> instance from all associated
127         * <code>encodingStyleURIs</code> and then removes this
128         * TypeMapping instance from the registry.
129         *
130         * @param mapping TypeMapping to remove
131         * @return <code>true</code> if specified <code>TypeMapping</code>
132         *     is removed from the TypeMappingRegistry; <code>false</code>
133         *     if the specified <code>TypeMapping</code> was not in the
134         *     <code>TypeMappingRegistry</code>
135         */
136        public boolean removeTypeMapping(TypeMapping mapping);
137    
138        /**
139         * Removes all registered TypeMappings and encodingStyleURIs
140         * from this TypeMappingRegistry.
141         */
142        public void clear();
143    }
144