com.ibm.as400.access
Class NetServer

java.lang.Object
  |
  +--com.ibm.as400.resource.Resource
        |
        +--com.ibm.as400.resource.ChangeableResource
              |
              +--com.ibm.as400.access.NetServer
All Implemented Interfaces:
java.io.Serializable

public class NetServer
extends ChangeableResource

The NetServer class represents the NetServer service on a server. This class allows the user to query and modify the state and configuration of the NetServer.

Note: Many of the attributes of NetServer are "pending". These attributes represent NetServer values that will take effect the next time the NetServer is (re)started. Wherever there is a pair of related attributes, where one is pending and one is non-pending, the "pending" attribute is read/write, while the non-pending attribute is read-only.
For example, to change the name of the NetServer, using a com.ibm.as400.access.NetServer object named "netServer":

  1. netServer.setAttributeValue(NetServer.NAME_PENDING, newName)
  2. netServer.commitAttributeChanges()
  3. netServer.end()
  4. netServer.start()

Note: This class does not start or end the QSERVER subsystem on the server. If the QSERVER subsystem is not running, various methods of this class will fail.

Note: Typically, methods which change the state or attributes of the NetServer require that the server user profile has *IOSYSCFG special authority. For example, starting or ending the NetServer requires *IOSYSCFG authority.

Note: This class uses some API fields that are available only when connecting to servers running OS/400 V5R1 or later.

The following attribute IDs are supported:

Use any of the above attribute IDs with getAttributeValue and setAttributeValue to access the attribute values for a NetServer.
Note: For the above attributes, getAttributeValue() should never return null. For String-valued attributes, if the current actual value of the corresponding property on the server is blank, getAttributeValue() will return "" (an empty String).

 import com.ibm.as400.access.*;
 import com.ibm.as400.resource.*;

 // Create a NetServer object for a specific server system.
 AS400 system = new AS400("MYSYSTEM", "MYUSERID", "MYPASSWORD");
 NetServer ns = new NetServer(system);

 try
 {

   // Get the name of the NetServer.
   System.out.println("Name: " +
               (String)ns.getAttributeValue(NetServer.NAME));

   // Get the CCSID of the NetServer.
   System.out.println("CCSID: " +
    ((Integer)ns.getAttributeValue(NetServer.CCSID)).intValue());

   // Get the pending CCSID of the NetServer.
   System.out.println("Pending CCSID: " +
    ((Integer)ns.getAttributeValue(NetServer.CCSID_PENDING)).intValue());

   // Get the "allow system name" value of the NetServer.
   System.out.println("'Allow system name': " +
    ((Boolean)ns.getAttributeValue(NetServer.ALLOW_SYSTEM_NAME)).booleanValue());

   // Set the (pending) description of the NetServer.
   // Note: Changes to "pending" attributes take effect after the NetServer
   // is ended and restarted.
   ns.setAttributeValue(NetServer.DESCRIPTION_PENDING, "The NetServer");
   ns.commitAttributeChanges();

   // Set the (pending) CCSID of the NetServer to 13488.
   ns.setAttributeValue(NetServer.CCSID_PENDING, new Integer(13488));

   // Set the (pending) "allow system name" value of the NetServer to true.
   ns.setAttributeValue(NetServer.ALLOW_SYSTEM_NAME_PENDING, new Boolean(true));

   // Commit the attribute changes (send them to the system).
   ns.commitAttributeChanges();

   // Print all the attribute values of the NetServer object.
   ResourceMetaData[] attributeMetaData = ns.getAttributeMetaData();
   for(int i = 0; i<attributeMetaData.length; i++)
   {
     Object attributeID = attributeMetaData[i].getID();
     Object value = resource.getAttributeValue(attributeID);
     System.out.println("Attribute " + attributeID + " = " + value);
   }

 }
 catch (ResourceException e) {
   e.printStackTrace();
 }
 finally {
   if (system != null) system.disconnectAllServices();
 }

See Also:
NetServerShare, NetServerFileShare, NetServerPrintShare, NetServerConnection, NetServerSession, Serialized Form

Field Summary
static java.lang.String ALLOW_SYSTEM_NAME
          Attribute ID for "allow system name".
static java.lang.String ALLOW_SYSTEM_NAME_PENDING
          Attribute ID for "allow system name (pending)".
static java.lang.String AUTHENTICATION_METHOD
          Attribute ID for "authentication method".
static java.lang.String AUTHENTICATION_METHOD_PENDING
          Attribute ID for "authentication method (pending)".
static java.lang.String AUTOSTART
          Attribute ID for "autostart".
static java.lang.String BROWSING_INTERVAL
          Attribute ID for "browsing interval".
static java.lang.String BROWSING_INTERVAL_PENDING
          Attribute ID for "browsing interval (pending)".
static java.lang.String CCSID
          Attribute ID for "server CCSID".
static java.lang.String CCSID_PENDING
          Attribute ID for "server CCSID (pending)".
static java.lang.String DESCRIPTION
          Attribute ID for "description".
static java.lang.String DESCRIPTION_PENDING
          Attribute ID for "description (pending)".
static java.lang.String DOMAIN
          Attribute ID for "domain name".
static java.lang.String DOMAIN_PENDING
          Attribute ID for "domain name (pending)".
static java.lang.String GUEST_USER_PROFILE
          Attribute ID for "guest user profile".
static java.lang.String GUEST_USER_PROFILE_PENDING
          Attribute ID for "guest profile (pending)".
static java.lang.String IDLE_TIMEOUT
          Attribute ID for "idle timeout".
static java.lang.String IDLE_TIMEOUT_PENDING
          Attribute ID for "idle timeout (pending)".
static java.lang.String LOGON_SUPPORT
          Attribute ID for "logon support".
static java.lang.String LOGON_SUPPORT_PENDING
          Attribute ID for "logon support (pending)".
static java.lang.String NAME
          Attribute ID for "name".
static java.lang.String NAME_PENDING
          Attribute ID for "name (pending)".
static java.lang.String WINS_ENABLEMENT
          Attribute ID for "WINS enablement".
static java.lang.String WINS_ENABLEMENT_PENDING
          Attribute ID for "WINS enabled (pending)".
static java.lang.String WINS_PRIMARY_ADDRESS
          Attribute ID for "WINS primary address".
static java.lang.String WINS_PRIMARY_ADDRESS_PENDING
          Attribute ID for "WINS primary address (pending)".
static java.lang.String WINS_SCOPE_ID
          Attribute ID for "WINS scope ID".
static java.lang.String WINS_SCOPE_ID_PENDING
          Attribute ID for "WINS scope ID (pending)".
static java.lang.String WINS_SECONDARY_ADDRESS
          Attribute ID for "WINS secondary address".
static java.lang.String WINS_SECONDARY_ADDRESS_PENDING
          Attribute ID for "WINS secondary address (pending)".
 
Constructor Summary
NetServer()
          Constructs a NetServer object.
NetServer(AS400 system)
          Constructs a NetServer object.
 
Method Summary
protected  void commitAttributeChanges(java.lang.Object[] attributeIDs, java.lang.Object[] values)
          Commits the specified attribute changes.
 void end()
          Ends the NetServer.
protected  void establishConnection()
          Establishes the connection to the server.
protected  void freezeProperties()
          Freezes any property changes.
 java.lang.Object getAttributeUnchangedValue(java.lang.Object attributeID)
          Returns the value of an attribute, disregarding any uncommitted changes.
 boolean isStarted()
          Indicates whether or not the NetServer is started.
 ResourceList listFileShares()
          Lists all file server shares currently associated with the NetServer.
 ResourceList listFileShares(java.lang.String shareName)
          Lists file server shares currently associated with the NetServer.
 ResourceList listPrintShares()
          Lists all print server shares currently associated with the NetServer.
 ResourceList listPrintShares(java.lang.String shareName)
          Lists print server shares currently associated with the NetServer.
 ResourceList listSessionConnections()
          Lists all session connections currently associated with the NetServer.
 ResourceList listSessions()
          Lists all sessions currently associated with the NetServer.
 ResourceList listShareConnections()
          Lists all share connections currently associated with the NetServer.
 void refreshAttributeValues()
          Refreshes the values for all attributes.
 void start()
          Starts the NetServer.
 void start(boolean reset)
          Starts and (optionally) resets the NetServer.
 
Methods inherited from class com.ibm.as400.resource.ChangeableResource
cancelAttributeChanges, commitAttributeChanges, commitAttributeChanges, fireAttributeChangesCanceled, fireAttributeChangesCommitted, fireAttributeValueChanged, fireResourceCreated, fireResourceDeleted, getAttributeUnchangedValue, getAttributeValue, getAttributeValue, hasUncommittedAttributeChanges, initializeAttributeValue, setAttributeValue, setAttributeValue
 
Methods inherited from class com.ibm.as400.resource.Resource
addActiveStatusListener, addPropertyChangeListener, addResourceListener, addVetoableChangeListener, arePropertiesFrozen, equals, fireAttributeValuesRefreshed, fireBusy, fireIdle, firePropertyChange, fireVetoableChange, getAttributeMetaData, getAttributeMetaData, getPresentation, getResourceKey, getSystem, isBidiEnabled, isConnectionEstablished, removeActiveStatusListener, removePropertyChangeListener, removeResourceListener, removeVetoableChangeListener, setPresentation, setResourceKey, setSystem, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ALLOW_SYSTEM_NAME

public static final java.lang.String ALLOW_SYSTEM_NAME
Attribute ID for "allow system name". This identifies a read-only Boolean attribute, which indicates whether to allow access to the server using the server's TCP/IP system name.

ALLOW_SYSTEM_NAME_PENDING

public static final java.lang.String ALLOW_SYSTEM_NAME_PENDING
Attribute ID for "allow system name (pending)". This identifies a Boolean attribute, which indicates whether to allow access to the server using the server's TCP/IP system name.

AUTHENTICATION_METHOD

public static final java.lang.String AUTHENTICATION_METHOD
Attribute ID for "authentication method". This identifies a read-only Integer attribute, which indicates the authentication method used to authenticate users. Note: This attribute is available only if the iSeries server has the OS/400 release following V5R1 or later. The value 0 indicates that the server authenticates with encrypted passwords. The value 1 indicates the server authenticates with Kerberos v5 tokens.

AUTHENTICATION_METHOD_PENDING

public static final java.lang.String AUTHENTICATION_METHOD_PENDING
Attribute ID for "authentication method (pending)". This identifies an Integer attribute, which indicates the authentication method used to authenticate users. Note: This attribute is available only if the iSeries server has the OS/400 release following V5R1 or later. The value 0 indicates that the server authenticates with encrypted passwords. The value 1 indicates the server authenticates with Kerberos v5 tokens.

AUTOSTART

public static final java.lang.String AUTOSTART
Attribute ID for "autostart". This identifies a Boolean attribute, which indicates whether or not the NetServer is to be started automatically when TCP is started.
Note: Due to API restrictions, if the server user profile does not have *IOSYSCFG authority, the value of this attribute is reported as false, regardless of the actual setting on the server.

BROWSING_INTERVAL

public static final java.lang.String BROWSING_INTERVAL
Attribute ID for "browsing interval". This identifies a read-only Integer attribute, which represents the amount of time, in milliseconds, between each server announcement that is used for browsing. A value of zero indicates that there will be no server announcements.

BROWSING_INTERVAL_PENDING

public static final java.lang.String BROWSING_INTERVAL_PENDING
Attribute ID for "browsing interval (pending)". This identifies an Integer attribute, which represents the amount of time, in milliseconds, between each server announcement that is used for browsing. A value of zero indicates that there will be no server announcements.

CCSID

public static final java.lang.String CCSID
Attribute ID for "server CCSID". This identifies a read-only Integer attribute, which represents the coded character set identifier for the NetServer.

This is the CCSID that is used for all clients connected to the server.
The default value for this field is the associated ASCII CCSID for the CCSID of the job used to start the server.
Note: A value of 0 indicates that the user would like to use the associated ASCII CCSID for the CCSID of the job used to start the server.


CCSID_PENDING

public static final java.lang.String CCSID_PENDING
Attribute ID for "server CCSID (pending)". This identifies an Integer attribute, which represents the pending coded character set identifier for the NetServer.

DESCRIPTION

public static final java.lang.String DESCRIPTION
Attribute ID for "description". This identifies a read-only String attribute, which represents the text description of the NetServer.

DESCRIPTION_PENDING

public static final java.lang.String DESCRIPTION_PENDING
Attribute ID for "description (pending)". This identifies a String attribute, which represents the pending text description of the NetServer.

DOMAIN

public static final java.lang.String DOMAIN
Attribute ID for "domain name". This identifies a read-only String attribute, which represents the domain name of the NetServer.

DOMAIN_PENDING

public static final java.lang.String DOMAIN_PENDING
Attribute ID for "domain name (pending)". This identifies a String attribute, which represents the pending domain name of the NetServer.

GUEST_USER_PROFILE

public static final java.lang.String GUEST_USER_PROFILE
Attribute ID for "guest user profile". This identifies a read-only String attribute, which represents the guest user profile for the NetServer. If no guest user profile is currently configured on the server, the value of this attribute is "" (an empty String).

Note: Guest support allows customers to have users accessing files and printers on the server, without the requirement of a user profile on the server. It limits access to data and allows customers to support a set of users who may only need print support but do not otherwise need server access.


GUEST_USER_PROFILE_PENDING

public static final java.lang.String GUEST_USER_PROFILE_PENDING
Attribute ID for "guest profile (pending)". This identifies a String attribute, which represents the pending guest profile for the NetServer. If no pending guest user profile is currently configured on the server, the value of this attribute is "" (an empty String).
Note: In order to change this attribute, the server user profile being used to access the NetServer must have *SECADM special authority. In addition, it requires *USE authority to the guest profile being set.

IDLE_TIMEOUT

public static final java.lang.String IDLE_TIMEOUT
Attribute ID for "idle timeout". This identifies a read-only Integer attribute, which represents the amount of time, in seconds, that a connection to the NetServer will remain active once activity has ceased on that connection. An idle time-out value of -1 indicates no autodisconnect.

IDLE_TIMEOUT_PENDING

public static final java.lang.String IDLE_TIMEOUT_PENDING
Attribute ID for "idle timeout (pending)". This identifies an Integer attribute, which represents the amount of time, in seconds, that a connection to the NetServer will remain active once activity has ceased on that connection. An idle time-out value of -1 indicates no autodisconnect.

LOGON_SUPPORT

public static final java.lang.String LOGON_SUPPORT
Attribute ID for "logon support". This identifies a read-only Boolean attribute, which indicates the logon server role for the server. If true, then the server is a logon server; if false, the server is not a logon server.
Note: This attribute corresponds to the "server role" field specified in the NetServer API's.

LOGON_SUPPORT_PENDING

public static final java.lang.String LOGON_SUPPORT_PENDING
Attribute ID for "logon support (pending)". This identifies a Boolean attribute, which indicates the logon server role for the server. If true, then the server is a logon server; if false, the server is not a logon server.

NAME

public static final java.lang.String NAME
Attribute ID for "name". This identifies a read-only String attribute, which represents the name of the NetServer.
Note: The NetServer name is uppercase on the server.

NAME_PENDING

public static final java.lang.String NAME_PENDING
Attribute ID for "name (pending)". This identifies a String attribute, which represents the pending name of the NetServer.
Note: The pending NetServer name is uppercase on the server.

WINS_ENABLEMENT

public static final java.lang.String WINS_ENABLEMENT
Attribute ID for "WINS enablement". This identifies a read-only Boolean attribute, which indicates whether the server uses a WINS server.

WINS_ENABLEMENT_PENDING

public static final java.lang.String WINS_ENABLEMENT_PENDING
Attribute ID for "WINS enabled (pending)". This identifies a Boolean attribute, which indicates whether the server uses a WINS server.

WINS_PRIMARY_ADDRESS

public static final java.lang.String WINS_PRIMARY_ADDRESS
Attribute ID for "WINS primary address". This identifies a read-only String attribute, which represents the IP address of the primary WINS server.

WINS_PRIMARY_ADDRESS_PENDING

public static final java.lang.String WINS_PRIMARY_ADDRESS_PENDING
Attribute ID for "WINS primary address (pending)". This identifies a String attribute, which represents the pending IP address of the primary WINS server.

WINS_SCOPE_ID

public static final java.lang.String WINS_SCOPE_ID
Attribute ID for "WINS scope ID". This identifies a read-only String attribute, which represents the network scope used by the WINS server. If no scope ID is currently configured on the server, the value of this attribute is "" (an empty String).

WINS_SCOPE_ID_PENDING

public static final java.lang.String WINS_SCOPE_ID_PENDING
Attribute ID for "WINS scope ID (pending)". This identifies a String attribute, which represents the pending network scope used by the WINS server. If no pending scope ID is currently configured on the server, the value of this attribute is "" (an empty String).

WINS_SECONDARY_ADDRESS

public static final java.lang.String WINS_SECONDARY_ADDRESS
Attribute ID for "WINS secondary address". This identifies a read-only String attribute, which represents the IP address of the secondary WINS server.

WINS_SECONDARY_ADDRESS_PENDING

public static final java.lang.String WINS_SECONDARY_ADDRESS_PENDING
Attribute ID for "WINS secondary address (pending)". This identifies a String attribute, which represents the pending IP address of the secondary WINS server.
Constructor Detail

NetServer

public NetServer()
Constructs a NetServer object. The system must be set before the object is used.

NetServer

public NetServer(AS400 system)
Constructs a NetServer object.
Parameters:
system - The server with which the NetServer is associated.
Method Detail

commitAttributeChanges

protected void commitAttributeChanges(java.lang.Object[] attributeIDs,
                                      java.lang.Object[] values)
                               throws ResourceException
Commits the specified attribute changes. This method fires an attributeChangesCommitted() ResourceEvent.
Overrides:
commitAttributeChanges in class ChangeableResource
Throws:
ResourceException - If an error occurs.

end

public void end()
         throws ResourceException
Ends the NetServer.
This method requires *IOSYSCFG special authority on the server.
Throws:
ResourceException - If an error occurs.

establishConnection

protected void establishConnection()
                            throws ResourceException
Establishes the connection to the server.

The method is called by the resource framework automatically when the connection needs to be established.

Overrides:
establishConnection in class Resource
Throws:
ResourceException - If an error occurs.

freezeProperties

protected void freezeProperties()
                         throws ResourceException
Freezes any property changes. After this is called, property changes should not be made. Properties are not the same thing as attributes. Properties are basic pieces of information which must be set to make the object usable, such as the system and the name.

The method is called by the resource framework automatically when the properties need to be frozen.

Overrides:
freezeProperties in class Resource
Throws:
ResourceException - If an error occurs.

getAttributeUnchangedValue

public java.lang.Object getAttributeUnchangedValue(java.lang.Object attributeID)
                                            throws ResourceException
Returns the value of an attribute, disregarding any uncommitted changes.
Overrides:
getAttributeUnchangedValue in class ChangeableResource
Parameters:
attributeID - Identifies the attribute.
Returns:
The attribute value, or null if the attribute value is not available.
Throws:
ResourceException - If an error occurs.

isStarted

public boolean isStarted()
                  throws ResourceException
Indicates whether or not the NetServer is started.
Returns:
true if the NetServer is started; false otherwise.
Throws:
ResourceException - If an error occurs.

listFileShares

public ResourceList listFileShares()
                            throws ResourceException
Lists all file server shares currently associated with the NetServer. The returned ResourceList contains NetServerFileShare objects.
Returns:
Information about all current file shares.
Throws:
ResourceException - If an error occurs.
See Also:
NetServerFileShare

listFileShares

public ResourceList listFileShares(java.lang.String shareName)
                            throws ResourceException
Lists file server shares currently associated with the NetServer. The returned ResourceList contains NetServerFileShare objects.
Parameters:
shareName - Name of shares to list. Can include wildcard ("*").
Returns:
Information about the specified file shares.
Throws:
ResourceException - If an error occurs.
See Also:
NetServerFileShare

listPrintShares

public ResourceList listPrintShares()
                             throws ResourceException
Lists all print server shares currently associated with the NetServer. The returned ResourceList contains NetServerPrintShare objects.
Returns:
Information about all current print shares.
Throws:
ResourceException - If an error occurs.
See Also:
NetServerPrintShare

listPrintShares

public ResourceList listPrintShares(java.lang.String shareName)
                             throws ResourceException
Lists print server shares currently associated with the NetServer. The returned ResourceList contains NetServerPrintShare objects.
Parameters:
shareName - Name of shares to list. Can include wildcard ("*").
Returns:
Information about the specified print shares.
Throws:
ResourceException - If an error occurs.
See Also:
NetServerPrintShare

listSessionConnections

public ResourceList listSessionConnections()
                                    throws ResourceException
Lists all session connections currently associated with the NetServer. The returned ResourceList contains NetServerConnection objects.
Returns:
Information about all current session connections.
Throws:
ResourceException - If an error occurs.
See Also:
NetServerConnection

listSessions

public ResourceList listSessions()
                          throws ResourceException
Lists all sessions currently associated with the NetServer. The returned ResourceList contains NetServerSession objects.
Returns:
Information about all current sessions.
Throws:
ResourceException - If an error occurs.
See Also:
NetServerSession

listShareConnections

public ResourceList listShareConnections()
                                  throws ResourceException
Lists all share connections currently associated with the NetServer. The returned ResourceList contains NetServerConnection objects.
Returns:
Information about all current share connections.
Throws:
ResourceException - If an error occurs.
See Also:
NetServerConnection

refreshAttributeValues

public void refreshAttributeValues()
                            throws ResourceException
Refreshes the values for all attributes. This does not cancel uncommitted changes. This method fires an attributeValuesRefreshed() ResourceEvent.
Overrides:
refreshAttributeValues in class ChangeableResource
Throws:
ResourceException - If an error occurs.

start

public void start()
           throws ResourceException
Starts the NetServer. If the NetServer is already started, this method does nothing.
This method requires *IOSYSCFG special authority on the server.
Note: This method does not reset the server.
Throws:
ResourceException - If an error occurs.

start

public void start(boolean reset)
           throws ResourceException
Starts and (optionally) resets the NetServer. If the NetServer is already started, this method does nothing.
This method requires *IOSYSCFG special authority on the server.

Note: Reset is used when the NetServer fails to start normally on the server. It is on the NetServer context menu so an administrator can use it. It basically does some under-the-covers cleanup, and is used infrequently. The times it would be used is if the server ended abnormally and there may be jobs or objects hanging around that need to be cleaned up before the server can start again. The reset does that.

Parameters:
reset - Whether or not the server is to be reset when started.
Throws:
ResourceException - If an error occurs.