1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package org.apache.river.discovery;
20
21 import java.io.IOException;
22 import java.net.Socket;
23 import java.nio.ByteBuffer;
24 import java.util.Collection;
25 import net.jini.core.constraint.InvocationConstraints;
26 import net.jini.io.UnsupportedConstraintException;
27
28 /**
29 * Interface implemented by classes which perform the client (discovering) side
30 * of unicast discovery.
31 *
32 * @author Sun Microsystems, Inc.
33 * @since 2.0
34 */
35 public interface UnicastDiscoveryClient extends DiscoveryFormatProvider {
36
37 /**
38 * Checks and returns normally if this client is capable of fulfilling the
39 * given absolute constraints. <code>null</code> constraints are
40 * considered equivalent to empty constraints.
41 *
42 * @param constraints the constraints to check, or <code>null</code>
43 * @throws UnsupportedConstraintException if unable to satisfy the
44 * specified constraints
45 * @throws SecurityException if the given constraints cannot be satisfied
46 * due to insufficient caller permissions
47 */
48 void checkUnicastDiscoveryConstraints(InvocationConstraints constraints)
49 throws UnsupportedConstraintException;
50
51 /**
52 * Performs the client side of unicast discovery, obtaining the returned
53 * response data over the provided socket using the given default and
54 * codebase verifier class loaders and collection of object stream context
55 * objects in a manner that satisfies the specified absolute constraints.
56 * Byte buffers containing the data sent and received so far over the given
57 * socket (for the unicast discovery protocol 2 handshake) are provided for
58 * use by formats which integrity protect or otherwise incorporate the
59 * handshake data. <code>null</code> constraints are considered equivalent
60 * to empty constraints.
61 *
62 * @param socket the socket on which to perform unicast discovery
63 * @param constraints the constraints to apply to unicast discovery, or
64 * <code>null</code>
65 * @param defaultLoader the class loader value (possibly <code>null</code>)
66 * to be passed as the <code>defaultLoader</code> argument to
67 * <code>RMIClassLoader</code> methods when unmarshalling the registrar
68 * proxy
69 * @param verifierLoader the class loader value (possibly
70 * <code>null</code>) to pass to {@link
71 * net.jini.security.Security#verifyCodebaseIntegrity
72 * Security.verifyCodebaseIntegrity}, if codebase integrity verification is
73 * used when unmarshalling the registrar proxy
74 * @param context the collection of context information objects (possibly
75 * <code>null</code>) to use when unmarshalling the registrar proxy
76 * @param sent a buffer containing the data already sent
77 * @param received a buffer containing the data already received
78 * @return the received unicast response data
79 * @throws IOException if an error occurs in interpreting received data or
80 * in formatting data to send
81 * @throws UnsupportedConstraintException if unable to satisfy the
82 * specified constraints
83 * @throws SecurityException if the given constraints cannot be satisfied
84 * due to insufficient caller permissions
85 * @throws ClassNotFoundException if the class of the discovered registrar
86 * cannot be resolved
87 * @throws NullPointerException if <code>socket</code>, <code>sent</code>,
88 * or <code>received</code> is <code>null</code>
89 */
90 UnicastResponse doUnicastDiscovery(Socket socket,
91 InvocationConstraints constraints,
92 ClassLoader defaultLoader,
93 ClassLoader verifierLoader,
94 Collection context,
95 ByteBuffer sent,
96 ByteBuffer received)
97 throws IOException, ClassNotFoundException;
98 }