Thomas Vachuska

Cleaned up a slew of Javadoc errors in preparation for switch over to Java 8.

Showing 39 changed files with 119 additions and 100 deletions
......@@ -30,9 +30,10 @@ public class RouteUpdate {
/**
* Specifies the type of a route update.
* <p/>
* <p>
* Route updates can either provide updated information for a route, or
* withdraw a previously updated route.
* </p>
*/
public enum Type {
/**
......
......@@ -439,11 +439,12 @@ public class Router implements RouteListener {
/**
* Processes adding a route entry.
* <p/>
* <p>
* Put new route entry into the radix tree. If there was an existing
* next hop for this prefix, but the next hop was different, then execute
* deleting old route entry. If the next hop is the SDN domain, we do not
* handle it at the moment. Otherwise, execute adding a route.
* </p>
*
* @param routeEntry the route entry to add
*/
......@@ -484,11 +485,12 @@ public class Router implements RouteListener {
/**
* Executes adding a route entry.
* <p/>
* <p>
* Find out the egress Interface and MAC address of next hop router for
* this route entry. If the MAC address can not be found in ARP cache,
* then this prefix will be put in routesWaitingOnArp queue. Otherwise,
* new route intent will be created and installed.
* </p>
*
* @param routeEntry the route entry to add
*/
......@@ -614,9 +616,10 @@ public class Router implements RouteListener {
/**
* Executes deleting a route entry.
* <p/>
* <p>
* Removes prefix from radix tree, and if successful, then try to delete
* the related intent.
* </p>
*
* @param routeEntry the route entry to delete
*/
......
......@@ -114,9 +114,10 @@ public class BgpRouteEntry extends RouteEntry {
/**
* Tests whether the route is originated from the local AS.
* <p/>
* <p>
* The route is considered originated from the local AS if the AS Path
* is empty or if it begins with an AS_SET.
* </p>
*
* @return true if the route is originated from the local AS, otherwise
* false
......@@ -134,9 +135,10 @@ public class BgpRouteEntry extends RouteEntry {
/**
* Gets the BGP Neighbor AS number the route was received from.
* <p/>
* <p>
* If the router is originated from the local AS, the return value is
* zero (BGP_AS_0).
* </p>
*
* @return the BGP Neighbor AS number the route was received from.
*/
......@@ -154,9 +156,10 @@ public class BgpRouteEntry extends RouteEntry {
/**
* Tests whether the AS Path contains a loop.
* <p/>
* <p>
* The test is done by comparing whether the AS Path contains the
* local AS number.
* </p>
*
* @param localAsNumber the local AS number to compare against
* @return true if the AS Path contains a loop, otherwise false
......@@ -175,9 +178,10 @@ public class BgpRouteEntry extends RouteEntry {
/**
* Compares this BGP route against another BGP route by using the
* BGP Decision Process.
* <p/>
* <p>
* NOTE: The comparison needs to be performed only on routes that have
* same IP Prefix.
* </p>
*
* @param other the BGP route to compare against
* @return true if this BGP route is better than the other BGP route
......@@ -389,8 +393,9 @@ public class BgpRouteEntry extends RouteEntry {
/**
* Compares whether two objects are equal.
* <p/>
* <p>
* NOTE: The bgpSession field is excluded from the comparison.
* </p>
*
* @return true if the two objects are equal, otherwise false.
*/
......@@ -422,8 +427,9 @@ public class BgpRouteEntry extends RouteEntry {
/**
* Computes the hash code.
* <p/>
* <p>
* NOTE: We return the base class hash code to avoid expensive computation
* </p>
*
* @return the object hash code
*/
......
......@@ -215,11 +215,11 @@ public class BgpSession extends SimpleChannelHandler {
/**
* Tests whether the session is closed.
* <p/>
* <p>
* NOTE: We use this method to avoid the Netty's asynchronous closing
* of a channel.
*
* @param return true if the session is closed
* </p>
* @return true if the session is closed
*/
boolean isClosed() {
return isClosed;
......@@ -1641,7 +1641,7 @@ public class BgpSession extends SimpleChannelHandler {
* @param errorCode the BGP NOTIFICATION Error Code
* @param errorSubcode the BGP NOTIFICATION Error Subcode if applicable,
* otherwise BgpConstants.Notifications.ERROR_SUBCODE_UNSPECIFIC
* @param payload the BGP NOTIFICATION Data if applicable, otherwise null
* @param data the BGP NOTIFICATION Data if applicable, otherwise null
* @return the message to transmit (BGP header included)
*/
ChannelBuffer prepareBgpNotification(int errorCode, int errorSubcode,
......
......@@ -29,15 +29,17 @@ import com.google.common.base.MoreObjects;
/**
* Represents a BGP daemon in SDN network.
* <p/>
* <p>
* Each BGP speaker has a attachment point, which includes a switch DPID and a
* switch port. Each BGP speaker has one MAC address and several IP addresses,
* which are used to peer with BGP peers outside the SDN network. For each
* peer outside the SDN network, we configure a different IP address to BGP
* speaker inside the SDN network.
* <p/>
* </p>
* <p>
* Each BGP speaker has a name, which is a unique identifying String that is
* used to reference this speaker in the configuration.
* </p>
*/
public class BgpSpeaker {
private final String name;
......
......@@ -28,8 +28,9 @@ import com.google.common.base.MoreObjects;
/**
* Represents an address of a {@link BgpSpeaker} configured on an
* {@link Interface}.
* <p/>
* <p>
* Each InterfaceAddress includes the interface name and an IP address.
* </p>
*/
public class InterfaceAddress {
private final ConnectPoint connectPoint;
......
......@@ -27,14 +27,12 @@ import org.slf4j.LoggerFactory;
import com.fasterxml.jackson.databind.ObjectMapper;
// TODO: As a long term solution, a module providing general network configuration to ONOS nodes should be used.
/**
* SDN-IP Config Reader provides IConfigInfoService
* by reading from an SDN-IP configuration file.
* It must be enabled on the nodes within the cluster
* SDN-IP Config Reader provides IConfigInfoService by reading from an
* SDN-IP configuration file. It must be enabled on the nodes within the cluster
* not running SDN-IP.
* <p/>
* TODO: As a long term solution, a module providing
* general network configuration to ONOS nodes should be used.
*/
public class SdnIpConfigReader implements SdnIpConfigService {
......@@ -85,7 +83,7 @@ public class SdnIpConfigReader implements SdnIpConfigService {
}*/
}
/**
/*
* To find the Interface which has longest matchable IP prefix (sub-network
* prefix) to next hop IP address.
*
......
......@@ -64,7 +64,7 @@ public class MastershipEvent extends AbstractEvent<MastershipEvent.Type, DeviceI
*
* @param type mastership event type
* @param device event device subject
* @param master master ID subject
* @param info role information
* @param time occurrence time
*/
public MastershipEvent(Type type, DeviceId device, RoleInfo info, long time) {
......
......@@ -25,8 +25,9 @@ public interface SparseAnnotations extends Annotations {
/**
* {@inheritDoc}
* <p/>
* <p>
* Note that this set includes keys for any attributes tagged for removal.
* </p>
*/
@Override
public Set<String> keys();
......
......@@ -46,7 +46,6 @@ public interface DeviceProviderService extends ProviderService<DeviceProvider> {
/**
* Sends information about all ports of a device. It is up to the core to
* determine what has changed.
* <p/>
*
* @param deviceId identity of the device
* @param portDescriptions list of device ports
......
......@@ -97,7 +97,7 @@ public final class DefaultTrafficTreatment implements TrafficTreatment {
/**
* Builds a list of treatments following the following order.
* Modifications -> Group -> Output (including drop)
* Modifications -&gt; Group -&gt; Output (including drop)
*/
public static final class Builder implements TrafficTreatment.Builder {
......
......@@ -27,7 +27,7 @@ public interface FlowRuleProviderService extends ProviderService<FlowRuleProvide
/**
* Signals that a flow rule that was previously installed has been removed.
*
* @param flowRule information about the removed flow
* @param flowEntry removed flow entry
*/
void flowRemoved(FlowEntry flowEntry);
......@@ -35,10 +35,8 @@ public interface FlowRuleProviderService extends ProviderService<FlowRuleProvide
* Pushes the collection of flow entries currently applied on the given
* device.
*
* @param flowRules collection of flow rules
* @param flowEntries collection of flow rules
*/
void pushFlowMetrics(DeviceId deviceId, Iterable<FlowEntry> flowEntries);
}
......
......@@ -49,7 +49,7 @@ public interface FlowRuleStore extends Store<FlowRuleBatchEvent, FlowRuleStoreDe
Iterable<FlowEntry> getFlowEntries(DeviceId deviceId);
/**
// TODO: Better description of method behavior.
* // TODO: Better description of method behavior.
* Stores a new flow rule without generating events.
*
* @param rule the flow rule to add
......@@ -58,6 +58,7 @@ public interface FlowRuleStore extends Store<FlowRuleBatchEvent, FlowRuleStoreDe
/**
* Stores a batch of flow rules.
*
* @param batchOperation batch of flow rules.
* @return Future response indicating success/failure of the batch operation
* all the way down to the device.
......@@ -66,7 +67,8 @@ public interface FlowRuleStore extends Store<FlowRuleBatchEvent, FlowRuleStoreDe
/**
* Invoked on the completion of a storeBatch operation.
* @param result
*
* @param event flow rule batch event
*/
void batchOperationComplete(FlowRuleBatchEvent event);
......@@ -75,7 +77,6 @@ public interface FlowRuleStore extends Store<FlowRuleBatchEvent, FlowRuleStoreDe
* when the provider indicates that the flow has been removed.
*
* @param rule the flow rule to delete
* @return true if the rule should be handled locally
*/
void deleteFlowRule(FlowRule rule);
......
......@@ -32,12 +32,13 @@ public interface HostAdminService {
/**
* Binds IP and MAC addresses to the given connection point.
* <p/>
* <p>
* The addresses are added to the set of addresses already bound to the
* connection point. If any of the fields in addresses is null, no change
* is made to the corresponding addresses in the store.
* {@link #unbindAddressesFromPort(PortAddresses)} must be use to unbind
* addresses that have previously been bound.
* </p>
*
* @param addresses address object containing addresses to add and the port
* to add them to
......
......@@ -114,9 +114,7 @@ public interface HostService {
/**
* Requests the host service to resolve the MAC address for the given IP
* address.
* <p/>
* This will trigger a notification to the host listeners if the MAC
* address. This will trigger a notification to the host listeners if the MAC
* address is found.
*
* @param ip IP address to find the MAC address for
......@@ -134,8 +132,7 @@ public interface HostService {
* Retrieves the addresses that have been bound to the given connection
* point.
*
* @param connectPoint the connection point to retrieve address bindings
* for
* @param connectPoint the connection point to retrieve address bindings for
* @return addresses bound to the port
*/
PortAddresses getAddressBindingsForPort(ConnectPoint connectPoint);
......
......@@ -36,9 +36,8 @@ public class PortAddresses {
/**
* Constructs a PortAddresses object for the given connection point, with a
* set of IP addresses and a MAC address.
* <p/>
* Both address parameters are optional and can be set to null.
* set of IP addresses and a MAC address. Both address parameters are
* optional and can be set to null.
*
* @param connectPoint the connection point these addresses are for
* @param ipAddresses a set of interface IP addresses
......
......@@ -26,8 +26,9 @@ import static com.google.common.base.Preconditions.checkNotNull;
/**
* Abstraction of an application level intent.
* <p/>
* <p>
* Make sure that an Intent should be immutable when a new type is defined.
* </p>
*/
public abstract class Intent implements BatchOperationTarget {
......
......@@ -19,8 +19,7 @@ import org.onlab.onos.net.flow.BatchOperationTarget;
/**
* Intent identifier suitable as an external key.
* <p/>
* This class is immutable.
* <p>This class is immutable.</p>
*/
public final class IntentId implements BatchOperationTarget {
......
......@@ -25,20 +25,20 @@ import java.util.concurrent.Future;
public interface IntentService {
/**
* Submits an intent into the system.
* <p/>
* <p>
* This is an asynchronous request meaning that any compiling or
* installation activities may be done at later time.
*
* </p>
* @param intent intent to be submitted
*/
void submit(Intent intent);
/**
* Withdraws an intent from the system.
* <p/>
* <p>
* This is an asynchronous request meaning that the environment may be
* affected at later time.
*
* </p>
* @param intent intent to be withdrawn
*/
void withdraw(Intent intent);
......@@ -54,10 +54,10 @@ public interface IntentService {
/**
* Submits a batch of submit &amp; withdraw operations. Such a batch is
* assumed to be processed together.
* <p/>
* <p>
* This is an asynchronous request meaning that the environment may be
* affected at later time.
*
* </p>
* @param operations batch of intent operations
*/
Future<IntentOperations> execute(IntentOperations operations);
......
......@@ -24,8 +24,9 @@ public enum IntentState {
* Signifies that the intent has been submitted and will start compiling
* shortly. However, this compilation may not necessarily occur on the
* local controller instance.
* <p/>
* <p>
* All intent in the runtime take this state first.
* </p>
*/
SUBMITTED,
......@@ -57,10 +58,11 @@ public enum IntentState {
* as an attempt to adapt to an anomaly in the network environment.
* This is a transitional state after which the intent will enter either
* {@link #FAILED} state or {@link #INSTALLING} state.
* <p/>
* <p>
* Exit to the {@link #FAILED} state may be caused by failure to compile
* or by compiling into the same set of installable intents which have
* previously failed to be installed.
* </p>
*/
RECOMPILING,
......
......@@ -28,11 +28,12 @@ public class OpticalConnectivityIntent extends Intent {
protected ConnectPoint dst;
/**
* Constructor.
* Creates an optical connectivity intent between the specified
* connection points.
*
* @param id ID for this new Intent object.
* @param src The source transponder port.
* @param dst The destination transponder port.
* @param appId application identification
* @param src the source transponder port
* @param dst the destination transponder port
*/
public OpticalConnectivityIntent(ApplicationId appId, ConnectPoint src, ConnectPoint dst) {
super(id(OpticalConnectivityIntent.class, src, dst),
......@@ -51,18 +52,18 @@ public class OpticalConnectivityIntent extends Intent {
}
/**
* Gets source transponder port.
* Returns the source transponder port.
*
* @return The source transponder port.
* @return source transponder port
*/
public ConnectPoint getSrcConnectPoint() {
return src;
}
/**
* Gets destination transponder port.
* Returns the destination transponder port.
*
* @return The source transponder port.
* @return source transponder port
*/
public ConnectPoint getDst() {
return dst;
......
......@@ -20,23 +20,26 @@
* <em>what</em> rather than the <em>how</em>. This makes such instructions
* largely independent of topology and device specifics, thus allowing them to
* survive topology mutations.
* <p/>
* <p>
* The controller core provides a suite of built-in intents and their compilers
* and installers. However, the intent framework is extensible in that it allows
* additional intents and their compilers or installers to be added
* dynamically at run-time. This allows others to enhance the initial arsenal of
* connectivity and policy-based intents available in base controller software.
* <p/>
* </p>
* <p>
* The following diagram depicts the state transition diagram for each top-level intent:<br>
* <img src="doc-files/intent-states.png" alt="ONOS intent states">
* <p/>
* </p>
* <p>
* The controller core accepts the intent specifications and translates them, via a
* process referred to as intent compilation, to installable intents, which are
* essentially actionable operations on the network environment.
* These actions are carried out by intent installation process, which results
* in some changes to the environment, e.g. tunnel links being provisioned,
* flow rules being installed on the data-plane, optical lambdas being reserved.
* <p/>
* </p>
* <p>
* After an intent is submitted by an application, it will be sent immediately
* (but asynchronously) into a compiling phase, then to installing phase and if
* all goes according to plan into installed state. Once an application decides
......@@ -48,7 +51,8 @@
* installable intents and instead result in a failed compile. If this occurs,
* only a change in the environment can trigger a transition back to the
* compiling state.
* <p/>
* </p>
* <p>
* Similarly, an issue may be encountered during the installation phase in
* which case the framework will attempt to recompile the intent to see if an
* alternate approach is available. If so, the intent will be sent back to
......@@ -61,12 +65,14 @@
* the intent, and if an alternate approach is available, its installation
* will be attempted. Otherwise, the original top-level intent will be parked
* in the failed state.
* <p/>
* </p>
* <p>
* Please note that all *ing states, depicted in orange, are transitional and
* are expected to last only a brief amount of time. The rest of the states
* are parking states where the intent may spent some time; except for the
* submitted state of course. There, the intent may pause, but only briefly,
* while the system determines where to perform the compilation or while it
* performs global recomputation/optimization across all prior intents.
* </p>
*/
package org.onlab.onos.net.intent;
......
......@@ -24,14 +24,16 @@ import static com.google.common.base.Preconditions.checkNotNull;
* External identity of a {@link org.onlab.onos.net.provider.Provider} family.
* It also carriers two designations of external characteristics, the URI
* scheme and primary/ancillary indicator.
* <p/>
* <p>
* The device URI scheme is used to determine applicability of a provider to
* operations on a specific device. The ancillary indicator serves to designate
* a provider as a primary or ancillary.
*
* </p>
* <p>
* A {@link org.onlab.onos.net.provider.ProviderRegistry} uses this designation
* to permit only one primary provider per device URI scheme. Multiple
* ancillary providers can register with the same device URI scheme however.
* </p>
*/
public class ProviderId {
......
......@@ -38,9 +38,10 @@ public interface ProviderRegistry<P extends Provider, S extends ProviderService<
* Unregisters the supplied provider. As a result the previously issued
* provider service will be invalidated and any subsequent invocations
* of its methods may throw {@link java.lang.IllegalStateException}.
* <p/>
* <p>
* Unregistering a provider that has not been previously registered results
* in a no-op.
* </p>
*
* @param provider provider to be unregistered
*/
......
......@@ -51,10 +51,11 @@ import org.onlab.util.Timer;
/**
* Monitors hosts on the dataplane to detect changes in host data.
* <p/>
* <p>
* The HostMonitor can monitor hosts that have already been detected for
* changes. At an application's request, it can also monitor and actively
* probe for hosts that have not yet been detected (specified by IP address).
* </p>
*/
public class HostMonitor implements TimerTask {
private DeviceService deviceService;
......
......@@ -49,8 +49,8 @@ import com.hazelcast.query.Predicate;
// TODO: implement Predicate, etc. if we need them.
/**
* Wrapper around IMap<byte[], byte[]> which serializes/deserializes
* Key and Value using StoreSerializer.
* Wrapper around IMap&lt;byte[], byte[]&gt; which serializes/deserializes
* key and value using StoreSerializer.
*
* @param <K> key type
* @param <V> value type
......
......@@ -71,7 +71,7 @@ public interface OpenFlowSwitchDriver extends OpenFlowSwitch {
public void handleNiciraRole(OFMessage m) throws SwitchStateException;
/**
* Handle OF 1.x (where x > 0) role messages.
* Handle OF 1.x (where x &gt; 0) role messages.
* @param m the role message to handle
* @throws SwitchStateException if the message received was
* not a nicira role or was malformed.
......
......@@ -747,8 +747,8 @@ class OFChannelHandler extends IdleStateAwareChannelHandler {
* the changes to ports will already be visible once the switch is
* activated. As a result, no notifications are sent out for these
* pending portStatus messages.
* @param h
* @throws SwitchStateException
*
* @param h the channel handler that received the message
*/
protected void handlePendingPortStatusMessages(OFChannelHandler h) {
try {
......
......@@ -52,15 +52,14 @@ import org.onlab.packet.ONOSLLDP;
import org.onlab.util.Timer;
import org.slf4j.Logger;
// TODO: add 'fast discovery' mode: drop LLDPs in destination switch but listen for flow_removed messages
/**
* Run discovery process from a physical switch. Ports are initially labeled as
* slow ports. When an LLDP is successfully received, label the remote port as
* fast. Every probeRate milliseconds, loop over all fast ports and send an
* LLDP, send an LLDP for a single slow port. Based on FlowVisor topology
* discovery implementation.
* <p/>
* TODO: add 'fast discovery' mode: drop LLDPs in destination switch but listen
* for flow_removed messages
*/
public class LinkDiscovery implements TimerTask {
......
......@@ -62,9 +62,6 @@ import org.slf4j.Logger;
* fast. Every probeRate milliseconds, loop over all fast ports and send an
* LLDP, send an LLDP for a single slow port. Based on FlowVisor topology
* discovery implementation.
*
* TODO: add 'fast discovery' mode: drop LLDPs in destination switch but listen
* for flow_removed messages
*/
@Deprecated
public class LinkDiscovery implements TimerTask {
......@@ -331,7 +328,6 @@ public class LinkDiscovery implements TimerTask {
* port.
*
* @param t timeout
* @throws Exception
*/
@Override
public void run(final Timeout t) {
......
......@@ -6,4 +6,4 @@
export JAVA_HOME=${JAVA_HOME:-/usr/lib/jvm/java-7-openjdk-amd64/}
cd $(dirname $0)/../apache-karaf-$KARAF_VERSION/bin
./client -h localhost "$@"
./client -h localhost -u karaf "$@"
......
......@@ -4,7 +4,7 @@
# -----------------------------------------------------------------------------
export JAVA_HOME=${JAVA_HOME:-/usr/lib/jvm/java-7-openjdk-amd64/}
export JAVA_OPTS="-Xms256M -Xmx2048M"
export JAVA_OPTS="${JAVA_OPTS:--Xms256M -Xmx2048M}"
cd /opt/onos
/opt/onos/apache-karaf-$KARAF_VERSION/bin/karaf "$@"
......
......@@ -12,6 +12,7 @@ respawn
env LANG=en_US.UTF-8
env JAVA_HOME=/usr/lib/jvm/java-7-openjdk-amd64
env NEW_JAVA_HOME=/usr/lib/jvm/java-8-oracle/
pre-stop script
/opt/onos/bin/onos halt 2>/opt/onos/var/stderr.log
......
......@@ -9,4 +9,4 @@
[ "$1" = "-w" ] && shift && onos-wait-for-start $1
[ -n "$1" ] && OCI=$1 && shift
client -h $OCI "$@" 2>/dev/null
client -h $OCI -u karaf "$@" 2>/dev/null
......
......@@ -76,10 +76,10 @@ public final class IpAddress implements Comparable<IpAddress> {
/**
* Converts a byte array and a given offset from the beginning of the
* array into an IP address.
* <p/>
* <p>
* The IP address is stored in network byte order (i.e., the most
* significant byte first).
*
* </p>
* @param value the value to use
* @param offset the offset in bytes from the beginning of the byte array
* @return an IP address
......
......@@ -17,13 +17,15 @@ package org.onlab.packet;
import java.util.Objects;
// TODO: Add support for IPv6 as well.
/**
* A class representing an IP prefix.
* TODO: Add support for IPv6 as well.
* <p/>
* A prefix consists of an IP address and a subnet mask.
* A class representing an IP prefix. A prefix consists of an IP address and
* a subnet mask.
* <p>
* NOTE: The stored IP address in the result IP prefix is masked to
* contain zeroes in all bits after the prefix length.
* </p>
*/
public final class IpPrefix {
// Maximum network mask length
......@@ -97,7 +99,7 @@ public final class IpPrefix {
* Converts a CIDR (slash) notation string (e.g., "10.1.0.0/16") into an
* IP prefix.
*
* @param value an IP prefix in string form, e.g. "10.1.0.0/16"
* @param address an IP prefix in string form, e.g. "10.1.0.0/16"
* @return an IP prefix
*/
public static IpPrefix valueOf(String address) {
......
......@@ -24,8 +24,8 @@ import org.apache.commons.lang3.concurrent.ConcurrentInitializer;
* Creates an instance of new ConcurrentHashMap on each {@link #get()} call.
* <p>
* To be used with
* {@link org.apache.commons.lang3.concurrent.ConcurrentUtils#createIfAbsent()
* ConcurrentUtils#createIfAbsent}
* {@link org.apache.commons.lang3.concurrent.ConcurrentUtils#createIfAbsent}
* </p>
*
* @param <K> ConcurrentHashMap key type
* @param <V> ConcurrentHashMap value type
......
......@@ -24,8 +24,9 @@ public interface MessageHandler {
/**
* Handles the message.
*
* @param message message.
* @throws IOException.
* @throws IOException if an error is encountered handling the message
*/
public void handle(Message message) throws IOException;
}
......
......@@ -318,10 +318,10 @@ public abstract class MessageStream<M extends Message> {
* Attempts to flush data, internal stream state and channel availability
* permitting. Invoked by the driver I/O loop during handling of writable
* selection key.
* <p/>
* <p>
* Resets the internal state flags {@code writeOccurred} and
* {@code writePending}.
*
* </p>
* @throws IOException if implicit flush failed
*/
void flushIfPossible() throws IOException {
......