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: */package org.apache.cxf.transport.http;
019:
020: import org.apache.cxf.message.Message;
021:
022: /**
023: *
024: * The HTTPConduit calls upon this object to establish trust just before a
025: * message within the HTTP Conduit is sent out. This object is based on
026: * the implementation of HTTP Conduit using java.net.URL and
027: * java.net.URLConnection implementations.
028: *
029: * The HttpURLConnection will be set up and connected, but no data
030: * yet sent (at least according to the JDK 1.5 default implemenation),
031: * and in the case of an HttpsURLConnection (again with caveat on
032: * particular java.net.HttpsURLConnection implemenation), the TLS handshake
033: * will be completed and certain TLS artifacts will be available.
034: * <p>
035: * Each MessageTrustDecider has a "logical" name that may be used in logging
036: * to help ensure the proper trust decision is being made for particular
037: * conduits.
038: */
039: public abstract class MessageTrustDecider {
040:
041: /**
042: * This field contains the "logical" name of this Message Trust Decider.
043: * This field is not assigned to be final, since an extension may be
044: * Spring initialized as a bean, have an appropriate setLogicalName
045: * method, and set this field.
046: */
047: protected String logicalName;
048:
049: /**
050: * This default constructor sets the "logical" name of the trust
051: * decider to be its class name.
052: */
053: protected MessageTrustDecider() {
054: logicalName = this .getClass().getName();
055: }
056:
057: /**
058: * This constructor is used to set the logical name of the
059: * trust decider.
060: */
061: protected MessageTrustDecider(String name) {
062: logicalName = name;
063: }
064:
065: /**
066: * This method returns the logical name of this trust decider.
067: * The name of the trust decider may be used in logging or auditing
068: * to make sure that the proper trust decision is being implemented.
069: */
070: public String getLogicalName() {
071: return logicalName;
072: }
073:
074: /**
075: * This method is called when a Message is about to be sent out
076: * over an HTTPConduit. Its implementation must throw the specified
077: * exception if the URL connection cannot be trusted for the
078: * message.
079: * <p>
080: * It is important to note that the Message structure at this point
081: * may not have any content, so any analysis of message content
082: * may be impossible.
083: * <p>
084: * This method gets invoked after URL.setRequestProperties() is called
085: * on the URL for the selected protocol.
086: * <P>
087: * The HTTPConduit calls this message on every redirect, however, it is
088: * impossible to tell where it has been redirected from.
089: *
090: * TODO: What are the exising Message Properties at the point of this call?
091: *
092: * @param conduitName This parameter contains the logical name
093: * for the conduit that this trust decider
094: * is being called from.
095: *
096: * @param connectionInfo This parameter contains information about
097: * the URL Connection. It may be subclassed depending
098: * on the protocol used for the URL. For "https",
099: * this argument will be a HttpsURLConnectionInfo.
100: * For "http", this argument will be
101: * HttpURLConnectionInfo.
102: *
103: * @param message This parameter contains the Message structure
104: * that governs where the message may be going.
105: *
106: * @throws UntrustedURLConnectionIOException
107: * The trust decider throws this exception if
108: * trust in the URLConnection cannot be established
109: * for the particular Message.
110: *
111: * @see HttpURLConnectionInfo
112: * @see HttpsURLConnectionInfo
113: */
114:
115: public abstract void establishTrust(String conduitName,
116: URLConnectionInfo connectionInfo, Message message)
117: throws UntrustedURLConnectionIOException;
118: }
|