com.sun.multicast.allocation
Class StaticAllocator

java.lang.Object
  |
  +--com.sun.multicast.allocation.StaticAllocator
All Implemented Interfaces:
java.lang.Cloneable, MulticastAddressAllocator

public class StaticAllocator
extends java.lang.Object
implements MulticastAddressAllocator, java.lang.Cloneable

A MulticastAddressAllocator for statically allocated addresses. This class allocates, deallocates, and otherwise manages multicast addresses using a static configuration file. It implements the MulticastAddressAllocator interface, so it may be used with other JRMS allocators through the MulticastAddressManager class. Most applications should access this class through the MulticastAddressManager class.

Each StaticAllocator keeps its state in a Properties object (and a few other data structures). In order to provide maximum reliability and because address allocations often persist across a long period of time, you may set a configuration file into which the allocator will save its state whenever it is changed. This allows address allocations to be preserved across multiple sessions. Since some platforms do not handle simultaneous file access well, each configuration file should be used by only one StaticAllocator object at once.

The initial state of the allocator may be read from a configuration file or a Properties object or set up by calling the addAddress method. Often, the configuration file is created by hand by an administrator, who enters multicast addresses into this file.

CAUTION:The addresses in the file need not be administratively scoped. However, caution should be used to ensure that there is no possibility of collisions (two hosts accidentally using the same address at the same time).

The configuration file is a property file in the format used by the java.util.Properties class. This file represents a list of properties. Each property consists of a key and a value, each of which is a String. There are two types of properties: scope properties and address state properties.

A scope property represents a scope in the scope list. The key for a scope property is a string of the form "Scope-N", where N is a number indicating the scope's position in the scope list (starting with 1 as the first scope in the list). The value has the form "startAddr-endAddr ttl name lang-tag", where startAddr and endAddr are the first and last addresses in the scope, ttl is the maximum ttl to be used within the scope, name is the name of the scope (surrounded by double quotes), and lang-tag is the language tag to be associated with the name. This format can't handle scope names that contain double quotes or scopes that have more than one name.

A lease property represents an existing lease. The key for a lease property is a string consisting of the letter "L", followed by a base64 encoding of the lease identifier. The value has the form "addressSet startTime duration", where addressSet consists of a left parenthesis, zero or more addressRanges separated by spaces, and a right parenthesis. startTime is a long representing the number of milliseconds since midnight GMT on January 1, 1970. duration is an int number of seconds. An addressRange is a starting address, a hyphen, and an ending address. And the addresses are IPv4 addresses in dotted decimal format.

The exact format of a property file is defined in The Java Language Specification. A typical line in a StaticAllocator configuration file looks like "LnTtc4jhWKJQaZLHQyGgLwQ\=\==(239.255.0.1-239.255.0.1)\ 938465910522\ -1". This line indicates a lease whose lease identifier is base64 encoded as "nTtc4jhWKJQaZLHQyGgLwQ==", which contains the single address 239.255.0.1, allocated from Sep 27, 1999 20:58:30 GMT for an indefinite period of time.

See Also:
MulticastAddressManager, MulticastAddressAllocator

Constructor Summary
StaticAllocator()
          Create a new StaticAllocator with no configuration file and no initial configuration.
StaticAllocator(java.util.Properties props)
          Create a new StaticAllocator with no configuration file and the specified initial configuration.
StaticAllocator(java.lang.String path)
          Create a new StaticAllocator using the specified configuration file.
 
Method Summary
 Lease allocateAddresses(Scope scope, int ttl, int count, java.util.Date requestedStartTime, java.util.Date requiredStartTime, int requestedDuration, int requiredDuration, AddressSet addressesRequested)
          Allocate one or more multicast addresses, matching the specified parameters.
 java.lang.Object clone()
          Creates a new StaticAllocator object that works like this one and returns it to the caller.
 java.lang.String getAllocatorName()
          Get the name used to identify the allocator.
 java.lang.String getConfigFilePath()
          Gets the configuration file's path name.
 java.util.Properties getConfiguration()
          Gets a Properties object that represents the current state of this object.
 ScopeList getScopeList(AddressType addressType)
          Get the multicast scope list.
 void init()
          Inform the allocator that the MulticastAddressManager is now managing it.
 void setConfigFilePath(java.lang.String path)
          Sets the configuration file's path name.
 void setConfiguration(java.util.Properties props)
          Sets the current state of this object based on a Properties object.
 void term()
          Inform the allocator that the MulticastAddressManager is no longer managing it.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StaticAllocator

public StaticAllocator()
                throws AddressAllocationException
Create a new StaticAllocator with no configuration file and no initial configuration. All state is stored in local objects and may be retrieved at any time with the getConfiguration method.
Throws:
AddressAllocationException - if the allocator could not be created

StaticAllocator

public StaticAllocator(java.util.Properties props)
                throws AddressAllocationException
Create a new StaticAllocator with no configuration file and the specified initial configuration. All state is stored in local objects and may be retrieved at any time with the getConfiguration method.
Throws:
AddressAllocationException - if the allocator could not be created

StaticAllocator

public StaticAllocator(java.lang.String path)
                throws AddressAllocationException
Create a new StaticAllocator using the specified configuration file. If the config file does not exist, it is created.
Parameters:
path - the pathname of the configuration file
Throws:
AddressAllocationException - if the allocator could not be created
Method Detail

getConfigFilePath

public java.lang.String getConfigFilePath()
Gets the configuration file's path name. If there is no configuration file, null is returned.
Returns:
the configuration file's path name (null if none)

setConfigFilePath

public void setConfigFilePath(java.lang.String path)
                       throws AddressAllocationException
Sets the configuration file's path name. The current state of the allocator is discarded and replaced with whatever is in the specified configuration file. If the path is null, the allocator's configuration is not changed, but it is no longer associated with any file.
Parameters:
path - the configuration file's path name
Throws:
AddressAllocationException - if the allocator could not be created

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Creates a new StaticAllocator object that works like this one and returns it to the caller. This is probably not a good idea, since the other StaticAllocator will share the same pool of addresses, but won't be coordinated with this one.
Overrides:
clone in class java.lang.Object
Returns:
a copy of this StaticAllocator object
Throws:
java.lang.CloneNotSupportedException - if an error occurs

getConfiguration

public java.util.Properties getConfiguration()
                                      throws AddressAllocationException
Gets a Properties object that represents the current state of this object. The format of the properties are described in the javadoc for this class.
Returns:
a Properties object that represents the current state of this object
Throws:
AddressAllocationException - if an error occurs

setConfiguration

public void setConfiguration(java.util.Properties props)
                      throws AddressAllocationException
Sets the current state of this object based on a Properties object. The format of the properties are described in the javadoc for this class.
Parameters:
props - a Properties object that is used to set the current state of this object
Throws:
AddressAllocationException - if an error occurs

init

public void init()
          throws AddressAllocationException
Inform the allocator that the MulticastAddressManager is now managing it. If this method throws an exception, the MulticastAddressManager will not accept it for management.

Note: This method should not be used by any classes other than MulticastAddressManager.

Specified by:
init in interface MulticastAddressAllocator
Throws:
AddressAllocationException - if the allocator does not want to be managed

term

public void term()
Inform the allocator that the MulticastAddressManager is no longer managing it. There is no way for the allocator to reject this.

Note: This method should not be used by any classes other than MulticastAddressManager.

Specified by:
term in interface MulticastAddressAllocator

getAllocatorName

public java.lang.String getAllocatorName()
Get the name used to identify the allocator. The application may supply this name as an argument to MulticastAddressManager.allocAddress() and MulticastAddressManager.findAllocator(). The name may not be null, should be unique, and must remain the same during the lifetime of a MulticastAddressAllocator object.
Specified by:
getAllocatorName in interface MulticastAddressAllocator
Following copied from interface: com.sun.multicast.allocation.MulticastAddressAllocator
Returns:
the allocator name

getScopeList

public ScopeList getScopeList(AddressType addressType)
                       throws AddressAllocationException
Get the multicast scope list.
Specified by:
getScopeList in interface MulticastAddressAllocator
Returns:
the multicast scope list
Throws:
AddressAllocationException - if an exception was encountered

allocateAddresses

public Lease allocateAddresses(Scope scope,
                               int ttl,
                               int count,
                               java.util.Date requestedStartTime,
                               java.util.Date requiredStartTime,
                               int requestedDuration,
                               int requiredDuration,
                               AddressSet addressesRequested)
                        throws AddressAllocationException,
                               NoAddressAvailableException
Allocate one or more multicast addresses, matching the specified parameters.

This method is used by the MulticastAddressManager when its allocateAddresses method has been called.

Specified by:
allocateAddresses in interface MulticastAddressAllocator
Parameters:
scope - the administrative scope requested
ttl - the maximum ttl that will be used
count - the number of multicast addresses requested (usually one)
requestedStartTime - the requested start time (null if now)
requiredStartTime - the latest acceptable start time (null if now)
requestedDuration - the requested duration in seconds (-1 if indefinite)
requiredDuration - the required duration in seconds (-1 if indefinite)
addressesRequested - a requested address set (null if any will do)
Returns:
the multicast address lease granted
Throws:
javax.jrms.addralloc.AddressAllocationException - if an error occurred
javax.jrms.addralloc.NoAddressAvailableException - if no address was available that met the requirements


JavaTM Reliable MulticastTM Service version 1.1
Copyright (c) 2001, Sun Microsystems Laboratories, All rights reserved.