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.soap; 021 022 /** 023 * <code>SOAPFactory</code> is a factory for creating various objects 024 * that exist in the SOAP XML tree. 025 * 026 * <code>SOAPFactory</code> can be 027 * used to create XML fragments that will eventually end up in the 028 * SOAP part. These fragments can be inserted as children of the 029 * <code>SOAPHeaderElement</code> or <code>SOAPBodyElement</code> or 030 * <code>SOAPEnvelope</code>. 031 * 032 * <code>SOAPFactory</code> also has methods to create 033 * <code>javax.xml.soap.Detail</code> objects as well as 034 * <code>java.xml.soap.Name</code> objects. 035 * 036 */ 037 public abstract class SOAPFactory { 038 039 public SOAPFactory() {} 040 041 /** 042 * Create a <code>SOAPElement</code> object initialized with the 043 * given <code>Name</code> object. 044 * 045 * @param name a <code>Name</code> object with the XML name for 046 * the new element 047 * @return the new <code>SOAPElement</code> object that was 048 * created 049 * @throws SOAPException if there is an error in creating the 050 * <code>SOAPElement</code> object 051 */ 052 public abstract SOAPElement createElement(Name name) throws SOAPException; 053 054 /** 055 * Create a <code>SOAPElement</code> object initialized with the 056 * given local name. 057 * 058 * @param localName a <code>String</code> giving the local name for 059 * the new element 060 * @return the new <code>SOAPElement</code> object that was 061 * created 062 * @throws SOAPException if there is an error in creating the 063 * <code>SOAPElement</code> object 064 */ 065 public abstract SOAPElement createElement(String localName) throws SOAPException; 066 067 /** 068 * Create a new <code>SOAPElement</code> object with the given 069 * local name, prefix and uri. 070 * 071 * @param localName a <code>String</code> giving the local name 072 * for the new element 073 * @param prefix the prefix for this <code>SOAPElement</code> 074 * @param uri a <code>String</code> giving the URI of the 075 * namespace to which the new element belongs 076 * @return the new <code>SOAPElement</code> object that was 077 * created 078 * @throws SOAPException if there is an error in creating the 079 * <code>SOAPElement</code> object 080 */ 081 public abstract SOAPElement createElement(String localName, String prefix, String uri) 082 throws SOAPException; 083 084 /** 085 * Creates a new <code>Detail</code> object which serves as a container 086 * for <code>DetailEntry</code> objects. 087 * <p> 088 * This factory method creates <code>Detail</code> objects for use in 089 * situations where it is not practical to use the <code>SOAPFault</code> 090 * abstraction. 091 * 092 * @return a <code>Detail</code> object 093 * @throws SOAPException if there is a SOAP error 094 */ 095 public abstract Detail createDetail() throws SOAPException; 096 097 /** 098 * Creates a new <code>Name</code> object initialized with the 099 * given local name, namespace prefix, and namespace URI. 100 * <p> 101 * This factory method creates <code>Name</code> objects for use in 102 * situations where it is not practical to use the <code>SOAPEnvelope</code> 103 * abstraction. 104 * 105 * @param localName a <code>String</code> giving the local name 106 * @param prefix a <code>String</code> giving the prefix of the namespace 107 * @param uri a <code>String</code> giving the URI of the namespace 108 * @return a <code>Name</code> object initialized with the given 109 * local name, namespace prefix, and namespace URI 110 * @throws SOAPException if there is a SOAP error 111 */ 112 public abstract Name createName(String localName, String prefix, String uri) 113 throws SOAPException; 114 115 /** 116 * Creates a new <code>Name</code> object initialized with the 117 * given local name. 118 * <p> 119 * This factory method creates <code>Name</code> objects for use in 120 * situations where it is not practical to use the <code>SOAPEnvelope</code> 121 * abstraction. 122 * 123 * @param localName a <code>String</code> giving the local name 124 * @return a <code>Name</code> object initialized with the given 125 * local name 126 * @throws SOAPException if there is a SOAP error 127 */ 128 public abstract Name createName(String localName) throws SOAPException; 129 130 /** 131 * Creates a new instance of <code>SOAPFactory</code>. 132 * 133 * @return a new instance of a <code>SOAPFactory</code> 134 * @throws SOAPException if there was an error creating the 135 * default <code>SOAPFactory</code> 136 */ 137 public static SOAPFactory newInstance() throws SOAPException { 138 139 try { 140 return (SOAPFactory) FactoryFinder.find(SF_PROPERTY, DEFAULT_SF); 141 } catch (Exception exception) { 142 throw new SOAPException("Unable to create SOAP Factory: " 143 + exception.getMessage()); 144 } 145 } 146 147 private static final String SF_PROPERTY = "javax.xml.soap.SOAPFactory"; 148 149 private static final String DEFAULT_SF = 150 "org.apache.axis.soap.SOAPFactoryImpl"; 151 }