Clean up

CHANGELOG.md

@@ -27,12 +27,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - `DatagramSocket` [#31](https://github.com/netsec-ethz/scion-java-client/pull/31)
   TODO: 
-  - TODO use AddressResolver/Cache!!!!! 
-  - document/test additional methods in socket (connect, get/set Cache/Path)
   - TODO cleanup search domains:
-    - rename method parameters from hostName to domainName
-    - test sub-domains, e.g. netsec.inf.ethz.ch and xyz.netsec.inf.ethz.ch
-    - Implement/Document assumeDestinationDispatcher() for AS-internal destinations.
     - FIX: DatagramSocket. receives stores path in cache when using FLUPKE!
     - WRITE test that covers the rawPath==0 part of the RequestPath constructor
 

src/main/java/org/scion/jpan/AbstractDatagramChannel.java

@@ -90,7 +90,7 @@ public PathPolicy getPathPolicy() {
   }
 
   /**
-   * Set the path policy. The default path policy is set in {@link PathPolicy#DEFAULT} If the
+   * Set the path policy. The default path policy is set in {@link PathPolicy#DEFAULT}. If the
    * channel is connected, this method will request a new path using the new policy.
    *
    * <p>After initially setting the path policy, it is used to request a new path during write() and
@@ -109,7 +109,7 @@ public void setPathPolicy(PathPolicy pathPolicy) throws IOException {
     }
   }
 
-  public ScionService getOrCreateService() {
+  protected ScionService getOrCreateService() {
     synchronized (stateLock) {
       if (service == null) {
         service = ScionService.defaultService();

src/main/java/org/scion/jpan/socket/DatagramSocket.java

@@ -163,6 +163,13 @@ public synchronized void bind(SocketAddress address) throws SocketException {
     }
   }
 
+  /**
+   * Connect to a destination using a specific path. See {@link
+   * org.scion.jpan.DatagramChannel#connect(RequestPath)} for details.
+   *
+   * @param path path to destination
+   * @see org.scion.jpan.DatagramChannel#connect(RequestPath)
+   */
   public synchronized void connect(RequestPath path) {
     try {
       channel.connect(path);
@@ -288,12 +295,12 @@ public void send(DatagramPacket packet) throws IOException {
         synchronized (pathCache) {
           path = pathCache.get(addr);
           if (path == null) {
-            path = channel.getPathPolicy().filter(channel.getOrCreateService().getPaths(addr));
+            path = channel.getPathPolicy().filter(channel.getOrCreateService2().getPaths(addr));
           } else if (path instanceof RequestPath
               && ((RequestPath) path).getExpiration() > Instant.now().getEpochSecond()) {
             // check expiration only for RequestPaths
             RequestPath request = (RequestPath) path;
-            path = channel.getPathPolicy().filter(channel.getOrCreateService().getPaths(request));
+            path = channel.getPathPolicy().filter(channel.getOrCreateService2().getPaths(request));
           }
           if (path == null) {
             throw new IOException("Address is not resolvable in SCION: " + packet.getAddress());
@@ -517,22 +524,52 @@ public void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf) {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * Get the currently connected path. The connected path is set during {@link
+   * #connect(RequestPath)} and may be refreshed when expired.
+   *
+   * @return the current Path or `null` if not path is connected.
+   * @see org.scion.jpan.DatagramChannel#getConnectionPath()
+   */
   public RequestPath getConnectionPath() {
     return (RequestPath) channel.getConnectionPath();
   }
 
+  /**
+   * The DatagramSocket caches paths from received packets. These are used to send responses to
+   * these packets. The method getCachedPath() looks up the path (if any) for the given address.
+   * Note that the cache size is limited, see {@link #setPathCacheCapacity(int)}.
+   *
+   * @return the cached Path or `null` if not path is found.
+   * @see #setPathCacheCapacity
+   */
   public synchronized Path getCachedPath(InetSocketAddress address) {
     synchronized (pathCache) {
       return pathCache.get(address);
     }
   }
 
+  /**
+   * The DatagramSocket caches paths from received packets. These are used to send responses to
+   * these packets. The method setPathCacheCapacity() sets the size of the path cache. The default
+   * size is 100.
+   *
+   * @see #getCachedPath
+   * @see #getPathCacheCapacity()
+   */
   public synchronized void setPathCacheCapacity(int capacity) {
     synchronized (pathCache) {
       pathCache.setCapacity(capacity);
     }
   }
 
+  /**
+   * The DatagramSocket caches paths from received packets. These are used to send responses to
+   * these packets. The method getPathCacheCapacity() gets the size of the path cache.
+   *
+   * @return the size of the path cache.
+   * @see #setPathCacheCapacity
+   */
   public synchronized int getPathCacheCapacity() {
     synchronized (pathCache) {
       return pathCache.getCapacity();
@@ -549,6 +586,12 @@ public synchronized org.scion.jpan.DatagramChannel getScionChannel() {
     return channel;
   }
 
+  /**
+   * @return The currently associated ScionService for this socket. This usually returns 'null' for
+   *     server side sockets because the service is only created for looking up SCION addresses and
+   *     ISD/AS codes, which should not be necessary for a server.
+   * @see org.scion.jpan.DatagramChannel#getService()
+   */
   public synchronized ScionService getService() {
     return channel.getService();
   }
@@ -557,6 +600,17 @@ public synchronized PathPolicy getPathPolicy() {
     return channel.getPathPolicy();
   }
 
+  /**
+   * Set the path policy. The default path policy is set in {@link PathPolicy#DEFAULT}. If the
+   * socket is connected, this method will request a new path using the new policy.
+   *
+   * <p>After initially setting the path policy, it is used to request a new path during write() and
+   * send() whenever a path turns out to be close to expiration.
+   *
+   * @param pathPolicy the new path policy
+   * @see PathPolicy#DEFAULT
+   * @see org.scion.jpan.DatagramChannel#setPathPolicy(PathPolicy)
+   */
   public synchronized void setPathPolicy(PathPolicy pathPolicy) throws IOException {
     channel.setPathPolicy(pathPolicy);
   }

src/main/java/org/scion/jpan/socket/SelectingDatagramChannel.java

@@ -106,4 +106,8 @@ public void close() throws IOException {
     super.close();
     selector.close();
   }
+
+  ScionService getOrCreateService2() {
+    return super.getOrCreateService();
+  }
 }