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 org.apache.axis2.jaxws.description;
021:
022: import org.apache.axis2.description.AxisService;
023: import org.apache.axis2.jaxws.ClientConfigurationFactory;
024: import org.apache.axis2.jaxws.description.builder.DescriptionBuilderComposite;
025: import org.apache.axis2.jaxws.description.impl.DescriptionFactoryImpl;
026:
027: import javax.xml.namespace.QName;
028: import java.net.URL;
029: import java.util.HashMap;
030: import java.util.List;
031:
032: /**
033: * Creates the JAX-WS metadata descritpion hierachy from some combinations of WSDL, Java class
034: * information including annotations, and (in the future) deployment descriptors.
035: */
036: public class DescriptionFactory {
037: /**
038: * The type of update being done for a particular Port. This is used by the JAX-WS service
039: * delegate on the CLIENT side. This is used as a parameter to the updateEndpoint factory
040: * method. An EndpointDescription will be returned corresponding to the port. GET_PORT:
041: * Return an SEI-based pre-existing port ADD_PORT: Return a Dispatch-only non-pre-existing
042: * port CREATE_DISPATCH: Return a Dispatch port; this is valid on either a pre-existing port
043: * (e.g. GET_PORT) or dynamic port (ADD_PORT)
044: */
045: public static enum UpdateType {
046: GET_PORT, ADD_PORT, CREATE_DISPATCH
047: }
048:
049: /** A DescrptionFactory can not be instantiated; all methods are static. */
050: private DescriptionFactory() {
051: }
052:
053: /**
054: * Create the initial ServiceDescription hierachy on the CLIENT side. This is intended to be
055: * called when the client creates a ServiceDelegate. Note that it will only create the
056: * ServiceDescription at this point. The EndpointDescription hierachy under this
057: * ServiceDescription will be created by the updateEndpoint factory method, which will be called
058: * by the ServiceDelegate once the port is known (i.e. addPort, getPort, or createDispatch).
059: *
060: * @param wsdlURL URL to the WSDL file to use; this may be null
061: * @param serviceQName The ServiceQName for this service; may not be null
062: * @param serviceClass The Service class; may not be null and must be assignable from
063: * javax.xml.ws.Service
064: * @return A ServiceDescription instance for a CLIENT access to the service.
065: * @see #updateEndpoint(ServiceDescription, Class, QName, ServiceDescription.UpdateType)
066: */
067: public static ServiceDescription createServiceDescription(
068: URL wsdlURL, QName serviceQName, Class serviceClass) {
069: return DescriptionFactoryImpl.createServiceDescription(wsdlURL,
070: serviceQName, serviceClass);
071: }
072:
073: /**
074: * Retrieve or create the EndpointDescription hierachy associated with an existing CLIENT side
075: * ServiceDescription for a particular port. If an EndpointDescritption already exists, it will
076: * be returned; if one does not already exist, it will be created. Note that if the SEI is null
077: * then the EndpointDescription returned will be for a Dispatch client only and it will not have
078: * an EndpointInterfaceDescription hierachy associated with it. If, at a later point, the same
079: * port is requested and an SEI is provided, the existing EndpointDescription will be updated
080: * with a newly-created EndpointInterfaceDescription hieracy.
081: *
082: * @param serviceDescription An existing client-side ServiceDescription. This must not be
083: * null.
084: * @param sei The ServiceInterface class. This can be null for adding a port or
085: * creating a Dispatch; it can not be null when getting a port.
086: * @param portQName The QName of the port. If this is null, the runtime will attempt
087: * to to select an appropriate port to use.
088: * @param updateType The type of the update: adding a port, creating a dispatch, or
089: * getting an SEI-based port.
090: * @return An EndpointDescription corresponding to the port.
091: * @see #createServiceDescription(URL, QName, Class)
092: * @see DescriptionFactory.UpdateType
093: */
094: public static EndpointDescription updateEndpoint(
095: ServiceDescription serviceDescription, Class sei,
096: QName portQName, DescriptionFactory.UpdateType updateType) {
097: return DescriptionFactoryImpl.updateEndpoint(
098: serviceDescription, sei, portQName, updateType);
099: }
100:
101: /**
102: * Create a full ServiceDescription hierachy on the SERVER side for EACH service implementation
103: * entry in the DescriptionBuilderComposite (DBC) map. Note that the associated SERVER side
104: * Axis description objects are also created. To create a single ServiceDescription hierarchy
105: * for a single service implementation class, use the factory method that takes a single class
106: * and returns a single ServiceDescription.
107: * <p/>
108: * A service implementation DBC entry is one that: (1) Is a class and not an interface (2)
109: * Carries a WebService or WebServiceProvider annotation.
110: * <p/>
111: * A DBC represents the information found in the service implementation class. There will be
112: * other DBC entries in the map for classes and interfaces associated with the service
113: * implementation, such as super classes, super interfaces, fault classes, and such.
114: * <p/>
115: * Note that map may contain > 1 service implementation DBC. A full ServiceDescriptionHierachy
116: * will be created for each service implementation DBC entry.
117: * <p/>
118: * Note that each ServiceDescription will have exactly one EndpointDescription corresponding to
119: * each service implementation.
120: *
121: * @param dbcMap A HashMap keyed on class name with a value for the DBC for that classname
122: * @return A List of ServiceDescriptions with the associated SERVER side hierachy created.
123: */
124: public static List<ServiceDescription> createServiceDescriptionFromDBCMap(
125: HashMap<String, DescriptionBuilderComposite> dbcMap) {
126: return DescriptionFactoryImpl
127: .createServiceDescriptionFromDBCMap(dbcMap);
128: }
129:
130: /**
131: * Create a full ServiceDescription hierachy on the SERVER side for a single service
132: * implementation class. To create process more than one service implementation at one time or
133: * to process them without causing the service implemenation classes to be loaded, use the
134: * factory method that takes a collection of DescriptionBuilderComposite objects and returns a
135: * collection of ServiceDescriptions.
136: * <p/>
137: * Note that the ServiceDescription will have exactly one EndpointDescription corresponding to
138: * the service implementation.
139: *
140: * @param serviceImplClass A Web Service implementation class (i.e. one that carries an
141: * WebService or WebServiceProvider annotation).
142: * @return A ServiceDescription with the associated SERVER side hierachy created.
143: */
144: public static ServiceDescription createServiceDescription(
145: Class serviceImplClass) {
146: return DescriptionFactoryImpl
147: .createServiceDescription(serviceImplClass);
148: }
149:
150: /**
151: * This provide very convenient way of creating an AxisService from an annotated java class.
152: *
153: * @param serviceImplClass A Web Service implementation class (i.e. one that carries an
154: * WebService or WebServiceProvider annotation).
155: * @return An AxisService instance
156: */
157: public static AxisService createAxisService(Class serviceImplClass) {
158: ServiceDescription serviceDescription = createServiceDescription(serviceImplClass);
159: EndpointDescription[] edArray = serviceDescription
160: .getEndpointDescriptions();
161: AxisService axisService = edArray[0].getAxisService();
162: return axisService;
163: }
164:
165: /**
166: * DO NOT USE THIS METHOD FOR PRODUCTION CODE. It has been deprecated and is only used to drive
167: * some testing. Note that the AxisService and associated Axis description objects ARE NOT
168: * created or updated by this factory method.
169: *
170: * @param serviceImplClass A service implementation class with annotations
171: * @param axisService A FULLY POPULATED AxisService including all of the underlying
172: * description objects such as AxisOperations.
173: * @return A ServiceDescription hierachy constructed (via Java reflection) from the service
174: * implementation class and tied via properties to the existing AxisService object.
175: * @deprecated Use {@link #createServiceDescriptionFromDBCMap(HashMap)}
176: */
177: public static ServiceDescription createServiceDescriptionFromServiceImpl(
178: Class serviceImplClass, AxisService axisService) {
179: return DescriptionFactoryImpl
180: .createServiceDescriptionFromServiceImpl(
181: serviceImplClass, axisService);
182: }
183:
184: /**
185: * Creates Client ConfigurationFactory used to create AxisConfiguration.
186: *
187: * @return A Client Configuration Factory's new instance. ClinetConfigurationFactory is
188: * Singleton.
189: */
190: public static ClientConfigurationFactory createClientConfigurationFactory() {
191: return DescriptionFactoryImpl.getClientConfigurationFactory();
192: }
193: }
|