URLDescriptor

java.lang.Object
- casa.agentCom.URLDescriptor

All Implemented Interfaces:

Comparable<URLDescriptor>
```
public class URLDescriptor
extends Object
implements Comparable<URLDescriptor>
```
URLDescriptor strings are of the form:
```
 casa:// [ user @ ] [ host ] [ : port ] [ / [ [   dir  / ]* [ file ] ] [# fragment] [? key [ = value ] [ & key [ = value ] ]* ] ]
                                          ----directory----                         -------------------data--------------------
                                          ---------path---------------
 
```
where
- user is an alphanumeric local identifier for an individual user.
- host is an IP address or host name. Default="localhost".
- port is a numeric value.
- path specifies a domain-specific description of an agent type.
- directory is part of the path.
- dir is an alphanumeric string.
- file is an alphanumeric string that is part of a path.
- fragment is an alphanumeric string designating a part of the agent (currently not used by CASA)
- data specifies various data elements that might be used by the agent.
- key is a key string (case sensitive) to retrieve the associated value.
- value is an alphanumeric string.
The following are directly supported key/value data pairs:
- lac=port is the port number of the agent's LAC. Note that the host of the LAC and the agent itself must be identical.
- indirect (no value part) indicates that messages should be routed trough the lac (which will forward it) instead of directly to the agent.
- via=URLDescriptor ... indicates a list of urls that all messages to this url should be proxied through. This is done by packing messages in the content of a proxy message. Typically, this is used to send a message through a CD instead of directly to another agent.
- directed (used in a CD url in a via datum only only, ignored otherwise) indicates that the message to be forwarded should be fowarded in directed mode ("+ syntax" -- tagged for the recipient, but broadcaste to all CD members).
- alias=URLDescriptor is the url to send any messages through. This is used for situations such as tunneling messages trough a firewall. Note that this alias URL should not contain any "&" characters (ie: it cannot contain multiple value parts (otherwise the parser or the outer URL may take the non-first values of the alias url as the outer ones).
for example:
agent12@www.cpsc.ucalgary.ca:8000 describes an agent called agent12 that is currently running and listening at port 8000
136.159.2.4/canada/alberta/calgary?lac=9000 describes an agent instance ("calgary") of type "canada/alberta" that may or may not be running on an unknown port, but it can be started or its port number obtained from the LAC running on port 9000.
URL strings are of two types:
- resolved where the current port of the agent is known. In this case, the path is usually ignored by the system.
- unresoved where the current port of the agent is not known, but the url may become resolved if the the path and lac ("?lac=") are known. This resolution may be done by sending a resolve request message to the LAC (which must have the same host as the agent), asking it to resolve the URL. If the agent is running, the LAC may simply return a resolved URL. If the agent is not currently running, the LAC may activate and run the agent on some port, then return the a resolved URL.
Copyright: Copyright 2003-2014, Knowledge Science Group, University of Calgary. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The Knowledge Science Group makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.
Version:

0.9

Author:

Rob Kremer, Vladimir Sedach

Field Summary

Fields
Modifier and Type	Field and Description
`private static CasaLispOperator`	`AGENT_IDENTIFIER` Lisp operator: (AGENT-IDENTIFIER)
`private static boolean`	`AMBIGUOUS_TAKEN_AS_LOCALHOST` If true, any URL which is ambiguous between a local and remote URL will silently resolve to the local URL.
`private Channel`	`channel`
`private String`	`data`
`private String`	`fragment`
`private InetAddress`	`host`
`private static List<URLDescriptor>`	`knownURLs`
`private int`	`mark`
`private static CasaLispOperator`	`NEW_URL` Lisp operator: (NEW-URL STRING)
`private String`	`path`
`private int`	`port`
`private long`	`timeWithdrawn`
`private static CasaLispOperator`	`URL__GET` Lisp operator: (NEW-URL STRING) Attempt to join the cooperation domain specified by the parameter URL.
`private static CasaLispOperator`	`URLS__GET` Lisp operator: (URLS.GET) Attempt to join the cooperation domain specified by the parameter URL.
`private String`	`user`
`private boolean`	`withdrawn`

Constructor Summary

Constructors
Modifier	Constructor and Description
`private`	`URLDescriptor(InetAddress host, int port)`
`private`	`URLDescriptor(int port)` Create a URL for the local machine on port
`private`	`URLDescriptor(String url_string)`
`private`	`URLDescriptor(String user, InetAddress host, int port, String path)`
`private`	`URLDescriptor(String user, InetAddress host, int port, String path, String data)`
`private`	`URLDescriptor(String user, InetAddress host, int port, String path, String data, String fragment)`
`private`	`URLDescriptor(String host, String port)`
`private`	`URLDescriptor(String host, String port, String user)`
`private`	`URLDescriptor(String user, String host, String port, String path)`
`private`	`URLDescriptor(URLDescriptor url)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`private int`	`compareHosts(InetAddress otherAddr)`
`int`	`compareTo(URLDescriptor o)`
`boolean`	`containsVia(URLDescriptor url)` Checks if the via data item contains the parameter url.
`void`	`copy(URLDescriptor url)` Copy the contents of the param url to this one.
`String`	`deleteDataValue(String key)` Removes a data key (and potentially a value) from the data part of the url (after the "?", separated by "&"s).
`private static URLDescriptor`	`disambiguate(URLDescriptor target, URLDescriptor x, URLDescriptor y)`
`boolean`	`equals(Object object)` Determines whether the given object is a `URLDescriptor` that describes that same agent as this `URLDescriptor`.
`static URLDescriptor`	`fromString(String url_string)`
`static URLDescriptor`	`fromString(TokenParser parser)` Constructs a URLDescriptor using the TokenParser input
`(package private) Channel`	`getChannel()`
`String`	`getData()`
`String`	`getDataValue(String key)` Check the data (after the "?") for the key and return the value
`static boolean`	`getDefaultAmbiguousURLtoLocal()`
`String`	`getDirectory()`
`String`	`getFile()`
`String`	`getFragment()`
`String`	`getFullAddress(URLDescriptor relativeTo)`
`InetAddress`	`getHost()`
`String`	`getHostAndPort()`
`String`	`getHostString()`
`boolean`	`getIndirect()`
`static URLDescriptor[]`	`getKnownURLs()`
`int`	`getLACport()`
`int`	`getMark()`
`String`	`getPath()`
`int`	`getPort()`
`String`	`getShortestName()`
`String`	`getUser()` GET
`Stack<URLDescriptor>`	`getViaStack()` Builds a stack of `URLDescriptor`s from the via data item in this url
`boolean`	`hasChannel()`
`boolean`	`hasData()`
`boolean`	`hasDataValue(String key)` Check the data (after the "?") for the existence of the key.
`boolean`	`hasFragment()`
`int`	`hashCode()`
`boolean`	`hasLACport()`
`boolean`	`hasPath()`
`boolean`	`hasPort()`
`boolean`	`hasUser()`
`private void`	`initialize(String user, InetAddress host, int port, String path, String data, String fragment)`
`boolean`	`isResolvable()`
`boolean`	`isResolved()`
`boolean`	`isWithdrawn()`
`boolean`	`local(URLDescriptor relativeTo)` Determine if this address is local relative to 'relativeTo'.
`static void`	`main(String[] args)`
`static URLDescriptor`	`make(InetAddress host, int port)`
`static URLDescriptor`	`make(int port)` Create a URL for the local machine on port
`static URLDescriptor`	`make(String url_string)`
`static URLDescriptor`	`make(String user, InetAddress host, int port, String path)`
`static URLDescriptor`	`make(String user, InetAddress host, int port, String path, String data)`
`static URLDescriptor`	`make(String user, InetAddress host, int port, String path, String data, String fragment)`
`static URLDescriptor`	`make(String host, String port)`
`static URLDescriptor`	`make(String host, String port, String user)`
`static URLDescriptor`	`make(String user, String host, String port, String path)`
`static URLDescriptor`	`make(URLDescriptor url)`
`int`	`mark()`
`private void`	`mergeWith(URLDescriptor url)`
`static URLset`	`peakURL(String s)`
`static String`	`popURL(String s)`
`URLDescriptor`	`popViaAtEnd()` Removes the last url from the via data item in the url ("?via=").
`static String`	`pushURL(String s, String url)`
`static String`	`pushURL(String s, String[] url)`
`void`	`pushViaAtEnd(URLDescriptor endURL)` Appends the endURL url to the end of the via* data item in the url ("?via=").*
`void`	`putViaStack(Stack<URLDescriptor> stack)` Replaces the via data item with one constructed from the stack parameter.
`static URLAndInt`	`readFirstURL(String s, int startAt)`
`void`	`resetMark()`
`private static URLDescriptor`	`resolve(URLDescriptor url)`
`Status`	`sendMessage(AbstractProcess sender, MLMessage message)`
`void`	`setChannel(Channel channel)`
`void`	`setData(String data)` Replace the entire data section in the URL.
`void`	`setDataValue(String key, String value)` Inserts a data key (and potentially a value) in to the data part of the url (after the "?", separated by "&"s).
`static void`	`setDefaultAmbiguousURLtoLocal(boolean b)` If b is true, any URL which is ambiguous between a local and remote URL will silently resolve to the local URL.
`void`	`setDirectory(String dir)`
`private void`	`setFile(String file)`
`void`	`setFragment(String frag)`
`private void`	`setHost(InetAddress host)`
`private void`	`setHost(String host)`
`void`	`setIndirect(boolean val)`
`void`	`setLACport(int lac_port)`
`private void`	`setPath(String path)`
`void`	`setPort(int port)`
`void`	`setPort(String port)`
`void`	`setUser(String user)`
`long`	`timeOfWithdrawal()`
`String`	`toString()` Simply calls #getFullAddress(null)
`String`	`toString(URLDescriptor relativeTo)` Simply calls #getFullAddress(relativeTo)
`String`	`toStringAgentIdentifier(boolean shortForm)`
`void`	`unresolve()` SET
`void`	`withdraw()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail
- knownURLs
```
private static List<URLDescriptor> knownURLs
```
- AMBIGUOUS_TAKEN_AS_LOCALHOST
```
private static boolean AMBIGUOUS_TAKEN_AS_LOCALHOST
```
  If true, any URL which is ambiguous between a local and remote URL will silently resolve to the local URL. If false, the ambiguity will cause a URLDescriptorException to be thrown.
- user
```
private String user
```
- host
```
private InetAddress host
```
- port
```
private int port
```
- path
```
private String path
```
- fragment
```
private String fragment
```
- data
```
private String data
```
- mark
```
private int mark
```
- withdrawn
```
private boolean withdrawn
```
- timeWithdrawn
```
private long timeWithdrawn
```
- NEW_URL
```
private static final CasaLispOperator NEW_URL
```
  Lisp operator: (NEW-URL STRING)
- AGENT_IDENTIFIER
```
private static final CasaLispOperator AGENT_IDENTIFIER
```
  Lisp operator: (AGENT-IDENTIFIER)
- URLS__GET
```
private static final CasaLispOperator URLS__GET
```
  Lisp operator: (URLS.GET)
  Attempt to join the cooperation domain specified by the parameter URL.
- URL__GET
```
private static final CasaLispOperator URL__GET
```
  Lisp operator: (NEW-URL STRING)
  Attempt to join the cooperation domain specified by the parameter URL.
- channel
```
private Channel channel
```

Constructor Detail

URLDescriptor
```
private URLDescriptor(String user,
                      InetAddress host,
                      int port,
                      String path)
```
Parameters:

user - is an alphanumeric string (e.g., agent1, 007) which is the name of the agent

host - is an IP address or name, e.g., 136.159.2.4, www.cpsc.ucalgary.ca

port - is a numeric value, e.g., 9000, 8080

path - is a slash-divided sequence of alphanumeric strings, e.g., canada/alberta/calgary

URLDescriptor

private URLDescriptor(String user,
                      InetAddress host,
                      int port,
                      String path,
                      String data)

URLDescriptor

private URLDescriptor(String user,
                      InetAddress host,
                      int port,
                      String path,
                      String data,
                      String fragment)

URLDescriptor

private URLDescriptor(URLDescriptor url)

URLDescriptor

private URLDescriptor(InetAddress host,
                      int port)

URLDescriptor
```
private URLDescriptor(int port)
```
Create a URL for the local machine on port

Parameters:

port - The port for the url (the trailing : part)

Throws:

UnknownHostException - If we can't get the IP address of the local machine for some reason

URLDescriptor

private URLDescriptor(String host,
                      String port)
               throws URLDescriptorException

Throws:: URLDescriptorException

URLDescriptor

private URLDescriptor(String host,
                      String port,
                      String user)
               throws URLDescriptorException

Throws:: URLDescriptorException

URLDescriptor

private URLDescriptor(String url_string)
               throws URLDescriptorException

Throws:: URLDescriptorException

URLDescriptor

private URLDescriptor(String user,
                      String host,
                      String port,
                      String path)
               throws URLDescriptorException

Throws:: URLDescriptorException

Method Detail

resolve

private static URLDescriptor resolve(URLDescriptor url)
                              throws AmbiguousURLException

Throws:: AmbiguousURLException

mergeWith

private void mergeWith(URLDescriptor url)

setDefaultAmbiguousURLtoLocal
```
public static void setDefaultAmbiguousURLtoLocal(boolean b)
```
If b is true, any URL which is ambiguous between a local and remote URL will silently resolve to the local URL. If false, the ambiguity will cause a AmbiguousURLException to be thrown.

Parameters:

b -

getDefaultAmbiguousURLtoLocal
```
public static boolean getDefaultAmbiguousURLtoLocal()
```
Returns:

if any URL which is ambiguous between a local and remote URL will silently resolve to the local URL, returns true. If the ambiguity will cause a URLDescriptorException to be thrown, returns false.

disambiguate

private static URLDescriptor disambiguate(URLDescriptor target,
                                          URLDescriptor x,
                                          URLDescriptor y)
                                   throws AmbiguousURLException

Throws:: AmbiguousURLException

getKnownURLs

public static URLDescriptor[] getKnownURLs()

make

public static URLDescriptor make(String user,
                                 InetAddress host,
                                 int port,
                                 String path)
                          throws URLDescriptorException

Throws:: URLDescriptorException

make

public static URLDescriptor make(String user,
                                 InetAddress host,
                                 int port,
                                 String path,
                                 String data)
                          throws URLDescriptorException

Throws:: URLDescriptorException

make

public static URLDescriptor make(String user,
                                 InetAddress host,
                                 int port,
                                 String path,
                                 String data,
                                 String fragment)
                          throws URLDescriptorException

Throws:: URLDescriptorException

make

public static URLDescriptor make(URLDescriptor url)
                          throws URLDescriptorException

Throws:: URLDescriptorException

make

public static URLDescriptor make(InetAddress host,
                                 int port)
                          throws URLDescriptorException

Throws:: URLDescriptorException

make
```
public static URLDescriptor make(int port)
                          throws URLDescriptorException
```
Create a URL for the local machine on port

Parameters:

port - The port for the url (the trailing : part)

Throws:

URLDescriptorException

UnknownHostException - If we can't get the IP address of the local machine for some reason

make

public static URLDescriptor make(String host,
                                 String port)
                          throws URLDescriptorException

Throws:: URLDescriptorException

make

public static URLDescriptor make(String host,
                                 String port,
                                 String user)
                          throws URLDescriptorException

Throws:: URLDescriptorException

make

public static URLDescriptor make(String url_string)
                          throws URLDescriptorException

Throws:: URLDescriptorException

fromString

public static URLDescriptor fromString(String url_string)
                                throws URLDescriptorException

Throws:: URLDescriptorException

make

public static URLDescriptor make(String user,
                                 String host,
                                 String port,
                                 String path)
                          throws URLDescriptorException

Throws:: URLDescriptorException

initialize

private void initialize(String user,
                        InetAddress host,
                        int port,
                        String path,
                        String data,
                        String fragment)

copy
```
public void copy(URLDescriptor url)
```
Copy the contents of the param url to this one.

Parameters:

url -

hasUser
```
public boolean hasUser()
```
Returns:

TRUE (HAS) iff the Agent is identified under any alphanumeric String

hasPath
```
public boolean hasPath()
```
Returns:

TRUE (HAS) iff the Agent contains an alphanumeric String as its path (see def. of path above)

hasPort
```
public boolean hasPort()
```

hasLACport
```
public boolean hasLACport()
```

hasFragment
```
public boolean hasFragment()
```

hasData
```
public boolean hasData()
```

isResolved
```
public boolean isResolved()
```

isResolvable
```
public boolean isResolvable()
```

unresolve
```
public void unresolve()
```
SET

setUser
```
public void setUser(String user)
```
Parameters:

user - is passed in order to set the Agent's name, i.e. Agent1

setHost

private void setHost(InetAddress host)

Parameters:: host -

setHost

private void setHost(String host)
              throws URLDescriptorException

Throws:: URLDescriptorException

setPort

public void setPort(String port)
             throws URLDescriptorException

Parameters:: port -
Throws:: URLDescriptorException

setPort
```
public void setPort(int port)
```
Parameters:

port -

setPath
```
private void setPath(String path)
```
Parameters:

path -

setLACport
```
public void setLACport(int lac_port)
```

setIndirect
```
public void setIndirect(boolean val)
```

setDirectory
```
public void setDirectory(String dir)
```

setFile
```
private void setFile(String file)
```

setData
```
public void setData(String data)
```
Replace the entire data section in the URL. It should be syntactically correct as it isn't checked (except for encoding). If you only want to add, delete, or replace a key see setDataValue(String,String) or deleteDataValue(String) .

Parameters:

data -

setFragment
```
public void setFragment(String frag)
```
Parameters:

frag -

setDataValue
```
public void setDataValue(String key,
                         String value)
```
Inserts a data key (and potentially a value) in to the data part of the url (after the "?", separated by "&"s). If a key is already present it will be replaced.

Parameters:

key -

value - may be null, indicating no value (just the key)

deleteDataValue
```
public String deleteDataValue(String key)
```
Removes a data key (and potentially a value) from the data part of the url (after the "?", separated by "&"s).

Parameters:

key -

guiValue - may be null, indicating no value (just the key)

getUser
```
public String getUser()
```
GET

getHost
```
public InetAddress getHost()
```
Returns:

getHostString
```
public String getHostString()
```

getPort
```
public int getPort()
```
Returns:

getPath
```
public String getPath()
```
Returns:

getHostAndPort
```
public String getHostAndPort()
```

getLACport
```
public int getLACport()
```

getIndirect
```
public boolean getIndirect()
```

getDirectory
```
public String getDirectory()
```
Returns:

The path (not including the File or Name) with the leading / and training /.

getFile
```
public String getFile()
```
Returns:

The File or AgentName not including any slashes.

getData
```
public String getData()
```
Returns:

getFragment
```
public String getFragment()
```
Returns:

getShortestName
```
public String getShortestName()
```

getDataValue
```
public String getDataValue(String key)
```
Check the data (after the "?") for the key and return the value

Parameters:

key - the key string, eg: ...?key=value&key2=value2

Returns:

the value, if the key is there and there is a value
"", if the key is there, but no value (eg: ...?key&...)
null, if the key is not found in the data

hasDataValue
```
public boolean hasDataValue(String key)
```
Check the data (after the "?") for the existence of the key.

Parameters:

key - the key string, eg: ...?key=value&key2=value2

Returns:

true if the key is found in the data; false otherwise.

local
```
public boolean local(URLDescriptor relativeTo)
```
Determine if this address is local relative to 'relativeTo'.

Parameters:

relativeTo -

Returns:

True iff

getFullAddress
```
public String getFullAddress(URLDescriptor relativeTo)
```
Returns:

String containing the host, port, '@'user and '/'path

toString
```
public String toString(URLDescriptor relativeTo)
```
Simply calls #getFullAddress(relativeTo)

Returns:

the entire address that corresponds to each Agent, YP, CD, or LAC For example, some of the prodefined Full addresses are: User: Agent1 --> 136.159.14.232:9005 ... it will also contain 136.159.14.232:13361 in order to show the IPSocket(port) that is using in order to connect with other Agents

toString
```
public String toString()
```
Simply calls #getFullAddress(null)

Overrides:

toString in class Object

Returns:

the entire address that corresponds to each Agent, YP, CD, or LAC

toStringAgentIdentifier

public String toStringAgentIdentifier(boolean shortForm)

fromString

public static URLDescriptor fromString(TokenParser parser)
                                throws URLDescriptorException

Constructs a URLDescriptor using the TokenParser input

Parameters:: parser -
Returns:
Throws:: URLDescriptorException

peakURL

public static URLset peakURL(String s)
                      throws URLDescriptorException

Throws:: URLDescriptorException

popURL

public static String popURL(String s)

readFirstURL

public static URLAndInt readFirstURL(String s,
                                     int startAt)
                              throws URLDescriptorException

Throws:: URLDescriptorException

pushURL

public static String pushURL(String s,
                             String url)

pushURL

public static String pushURL(String s,
                             String[] url)

main

public static void main(String[] args)

compareHosts

private int compareHosts(InetAddress otherAddr)

equals
```
public boolean equals(Object object)
```
Determines whether the given object is a URLDescriptor that describes that same agent as this URLDescriptor. The argument object may be a string, in which case, an attempt is made to parse it, and if it is a legitimate URLDescriptor, then it is compared as such.

Overrides:

equals in class Object

Parameters:

object - The object to compare to this URLDescriptor.

Returns:

true if the object is a URLDescriptor and has the same hosts and ports, OR if either of the ports are 0 (undefined) then the hosts and paths are compare instead; false otherwise.

compareTo
```
public int compareTo(URLDescriptor o)
```
Specified by:

compareTo in interface Comparable<URLDescriptor>

hashCode
```
public int hashCode()
```
Overrides:

hashCode in class Object

mark
```
public int mark()
```

getMark
```
public int getMark()
```
Returns:

resetMark
```
public void resetMark()
```

isWithdrawn
```
public boolean isWithdrawn()
```
Returns:

timeOfWithdrawal
```
public long timeOfWithdrawal()
```

withdraw
```
public void withdraw()
```

getViaStack
```
public Stack<URLDescriptor> getViaStack()
```
Builds a stack of URLDescriptors from the via data item in this url

Returns:

a stack of URLDescriptors.

putViaStack
```
public void putViaStack(Stack<URLDescriptor> stack)
```
Replaces the via data item with one constructed from the stack parameter.

Parameters:

stack - the stack from which to construct the new via data item.

pushViaAtEnd
```
public void pushViaAtEnd(URLDescriptor endURL)
```
Appends the endURL url to the end of the via data item in the url ("?via=").

Parameters:

endURL - the url to append to the via data item.

popViaAtEnd

public URLDescriptor popViaAtEnd()

Removes the last url from the via data item in the url ("?via=").

Returns:

the url removed, or null if there was no viviaa item.

containsVia

public boolean containsVia(URLDescriptor url)

Checks if the via data item contains the parameter url.

Parameters:

url - the url to search for

Returns:

true iff the via contains the parameter url.

setChannel

public void setChannel(Channel channel)

getChannel

Channel getChannel()

hasChannel

public boolean hasChannel()

sendMessage

public Status sendMessage(AbstractProcess sender, MLMessage message) throws IOException, URLDescriptorException

Throws:

IOException

URLDescriptorException

Class URLDescriptor

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

knownURLs

AMBIGUOUS_TAKEN_AS_LOCALHOST

user

host

port

path

fragment

data

mark

withdrawn

timeWithdrawn

NEW_URL

AGENT_IDENTIFIER

URLS__GET

URL__GET

channel

Constructor Detail

URLDescriptor

URLDescriptor

URLDescriptor

URLDescriptor

URLDescriptor

URLDescriptor

URLDescriptor

URLDescriptor

URLDescriptor

URLDescriptor

Method Detail

resolve

mergeWith

setDefaultAmbiguousURLtoLocal

getDefaultAmbiguousURLtoLocal

disambiguate

getKnownURLs

make

make

make

make

make

make

make

make

make

fromString

make

initialize

copy

hasUser

hasPath

hasPort

hasLACport

hasFragment

hasData

isResolved

isResolvable

unresolve

setUser

setHost

setHost

setPort

setPort

setPath

setLACport

setIndirect

setDirectory

setFile

setData

setFragment

setDataValue

deleteDataValue

getUser

getHost

getHostString

getPort