netapp.manage
Class NaServer

java.lang.Object
  netapp.manage.NaServer

Direct Known Subclasses:

NaProxyServer

public class NaServer

extends java.lang.Object

A class used to connect to servers and invoke APIs.

Field Summary

static int	HOSTSEQUIV Deprecated. As of SDK version 1.4
static int	KEYSTORE_TYPE_JKS
static int	KEYSTORE_TYPE_PKCS12
static int	LOGIN_PASSWORD Deprecated. As of SDK version 1.4
static int	SERVER_TYPE_AGENT
static int	SERVER_TYPE_DFM
static int	SERVER_TYPE_FILER
static int	SERVER_TYPE_NETCACHE
static int	SERVER_TYPE_OCUM
static int	STYLE_CERTIFICATE
static int	STYLE_HOSTSEQUIV
static int	STYLE_LOGIN_PASSWORD
static int	STYLE_RPC
static int	TRANSPORT_TYPE_HTTP
static int	TRANSPORT_TYPE_HTTPS

Constructor Summary

NaServer(java.net.InetAddress serverAddr)
Create a server API object with server type SERVER_TYPE_FILER and API version 1.0.

NaServer(java.net.InetAddress serverAddr, int majorVersion, int minorVersion)
Create a server API object with server type SERVER_TYPE_FILER

NaServer(java.lang.String serverName)
Create a server API object with server type SERVER_TYPE_FILER and API version 1.0.

NaServer(java.lang.String serverName, int majorVersion, int minorVersion)
Create a server API object with server type SERVER_TYPE_FILER

Method Summary

void	close() Close any connections used by this object.
void	disableHostnameVerification() Disables Hostname verification by the client during server certificate verification.
void	disableServerCertVerification() Disables the server certificate verification by the client.
void	disableSSLv3() Disables SSLv3 protocol for use over HTTPS Transport.
void	disableTLS() Disables TLS protocol for use over HTTPS Transport.
void	enableHostnameVerification() Enables Hostname verification by the client during server certificate verification.
void	enableServerCertVerification() Enables the server certificate verification by the client.
void	enableSSLv3() Enables SSLv3 protocol for use over HTTPS Transport.
void	enableTLS() Enables TLS protocol for use on connection over HTTPS Transport.
static java.lang.String	getApplicationName() Returns the name of the client application.
java.lang.String	getCookie() Gets the cookie header that will be added to the outgoing HTTP request.
int	getPort() Get the TCP port used for API invocations on the server.
int	getServerType() Get the server type, which is one of the SERVER_TYPE_ values.
int	getStyle() Get the current authentication style.
int	getTimeout() Get the connection timeout value in seconds for the current server context.
int	getTransportType() Get the transport type, which is one of the TRANSPORT_TYPE_ values.
java.lang.String	getVserver() Gets the name of the vserver to which a Cluster API need to be tunneled from a Cluster Management Interface.
NaElement	getXMLParseInput(java.lang.String args) Parses the given API request in the form of XML and builds an NaElement of it.
NaElement	invokeElem(NaElement xi) Invoke a single API request.
java.lang.String	invokeElemForXML(NaElement xi) Invoke a single ONTAPI API.
boolean	isHostnameVerificationEnabled() Determines whether Hostname verification is enabled by the client during server certificate verification.
boolean	isServerCertVerificationEnabled() Determines whether Server certificate verification is enabled by the client.
boolean	isSSLv3Enabled() Determines whether SSLv3 protocol is enabled for use over HTTPS Transport.
boolean	isTLSEnabled() Determines whether TLS protocol is enabled for use over HTTPS Transport.
void	setAdminUser(java.lang.String login, java.lang.String password) Set the login and password used for authenticating when an API is invoked.
void	setApiVersion(int majorVersion, int minorVersion) Set the API version for requests.
static void	setApplicationName(java.lang.String appName) Sets the name of the client application.
void	setCookie(java.lang.String cookieValue) Adds a cookie header to the outgoing HTTP request.
void	setKeepAliveEnabled(boolean enabled) Turn HTTP keep alives on or off.
void	setKeyStore(java.lang.String keyStore, java.lang.String keyStorePasswd) Sets the location of the keystore file where the client certificate and the key reside.
void	setKeyStore(java.lang.String keyStore, java.lang.String keyStorePasswd, java.lang.String keyPasswd) Sets the location of the keystore file where the client certificate and the key reside.
void	setKeyStoreType(int keyStoreType) Sets the keystore type for client certificates.
void	setPort(int tcpPort) Set the TCP port used for API invocations on the server.
void	setServerType(int serverType) Set the URI and TCP port appropriate for the given server type.
void	setSnoop(int level) Set the snoop (debugging) level.
void	setStyle(int style) Set the authentication style for subsequent API authentications.
void	setTimeout(int timeout) Set the connection timeout value in seconds for the current server context.
void	setTransportType(int transportType) Set the transport type.
void	setTrustStore(java.lang.String trustStore) Sets the default location of the truststore containing the certificates of the trusted Certificate Authorities required for authenticating the server.
void	setVfilerTunneling(java.lang.String vfiler) Set the name of the vfiler on which the Data ONTAP API commands need to be invoked.
void	setVserver(java.lang.String vserver) Sets the name of the vserver to which a Cluster API need to be tunneled from a Cluster Management Interface.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SERVER_TYPE_FILER

public static final int SERVER_TYPE_FILER

See Also:

Constant Field Values

SERVER_TYPE_NETCACHE

public static final int SERVER_TYPE_NETCACHE

See Also:

Constant Field Values

SERVER_TYPE_AGENT

public static final int SERVER_TYPE_AGENT

See Also:

Constant Field Values

SERVER_TYPE_DFM

public static final int SERVER_TYPE_DFM

See Also:

Constant Field Values

SERVER_TYPE_OCUM

public static final int SERVER_TYPE_OCUM

See Also:

Constant Field Values

TRANSPORT_TYPE_HTTP

public static final int TRANSPORT_TYPE_HTTP

See Also:

Constant Field Values

TRANSPORT_TYPE_HTTPS

public static final int TRANSPORT_TYPE_HTTPS

See Also:

Constant Field Values

STYLE_LOGIN_PASSWORD

public static final int STYLE_LOGIN_PASSWORD

See Also:

Constant Field Values

STYLE_HOSTSEQUIV

public static final int STYLE_HOSTSEQUIV

See Also:

Constant Field Values

STYLE_RPC

public static final int STYLE_RPC

See Also:

Constant Field Values

STYLE_CERTIFICATE

public static final int STYLE_CERTIFICATE

See Also:

Constant Field Values

KEYSTORE_TYPE_JKS

public static final int KEYSTORE_TYPE_JKS

See Also:

Constant Field Values

KEYSTORE_TYPE_PKCS12

public static final int KEYSTORE_TYPE_PKCS12

See Also:

Constant Field Values

LOGIN_PASSWORD

public static final int LOGIN_PASSWORD

Deprecated. As of SDK version 1.4

See Also:

Constant Field Values

HOSTSEQUIV

public static final int HOSTSEQUIV

Deprecated. As of SDK version 1.4

See Also:

Constant Field Values

Constructor Detail

NaServer

public NaServer(java.net.InetAddress serverAddr)

Create a server API object with server type SERVER_TYPE_FILER and API version 1.0.

Parameters:

serverAddr - The IP address(IPv4 or IPv6) of the API server.

NaServer

public NaServer(java.lang.String serverName)
         throws java.net.UnknownHostException

Create a server API object with server type SERVER_TYPE_FILER and API version 1.0.

Parameters:

serverName - The name of the API server.

Throws:

java.net.UnknownHostException - if the hostname is not known.

NaServer

public NaServer(java.net.InetAddress serverAddr,
                int majorVersion,
                int minorVersion)

Create a server API object with server type SERVER_TYPE_FILER

Parameters:

serverAddr - The IP address(IPv4 or IPv6) of the API server.

majorVersion - The major API version number required, for example "1" if version 1.0 is required.

minorVersion - The minor API version number required, for example "0" if version 1.0 is required.

For DataFabric Manager APIs, pass 1.0 as the major and minor version numbers.

NaServer

public NaServer(java.lang.String serverName,
                int majorVersion,
                int minorVersion)
         throws java.net.UnknownHostException

Create a server API object with server type SERVER_TYPE_FILER

Parameters:

serverName - The name of the API server.

majorVersion - The major API version number required, for example "1" if version 1.0 is required.

minorVersion - The minor API version number required, for example "0" if version 1.0 is required.

For DataFabric Manager APIs, pass 1.0 as the major and minor version numbers.

Throws:

java.net.UnknownHostException - if the hostname is not known.

Method Detail

setApiVersion

public void setApiVersion(int majorVersion,
                          int minorVersion)

Set the API version for requests.

Parameters:

majorVersion - The major API version number required, for example "1" if version 1.0 is required.

minorVersion - The minor API version number required, for example "0" if version 1.0 is required.

For DataFabric Manager APIs, pass 1.0 as the major and minor version numbers.

close

public void close()

Close any connections used by this object.

setKeepAliveEnabled

public void setKeepAliveEnabled(boolean enabled)

Turn HTTP keep alives on or off. The default is off. If keep alives are enabled, you must call close() when you are done using this object.

Parameters:

enabled - Set to true to turn on keep alives.

setPort

public void setPort(int tcpPort)

Set the TCP port used for API invocations on the server.

Following are the default ports on the storage system used for Data ONTAP API communication:

• HTTP transport - 80
• HTTPS transport - 443

Following are the default ports on the OnCommand Unified Manager 5.2 or earlier servers for API communication:

• HTTP transport - 8088
• HTTPS transport - 8488

Following is the only supported port on the OnCommand Unified Manager 6.0 or later servers for API communication:

• HTTPS transport - 443

Use the above port numbers as input to this API if the server has default port settings.

Parameters:

tcpPort - The TCP server port to use.

getPort

public int getPort()

Get the TCP port used for API invocations on the server.

setTimeout

public void setTimeout(int timeout)

Set the connection timeout value in seconds for the current server context.

Sets a connection timeout for the following actions:

Establishing a connection with the server.

Reading data from the server socket used for API communication.

Note: Timeout value cannot be set for RPC authentication style.

Parameters:

timeout - The timeout value in seconds and should be zero or a positive number.

If it is non-zero, the server uses non-blocking socket connection. If it is zero, the server uses blocking connection, which is the default behavior.

getTimeout

public int getTimeout()

Get the connection timeout value in seconds for the current server context.

getServerType

public int getServerType()

Get the server type, which is one of the SERVER_TYPE_ values.

setServerType

public void setServerType(int serverType)

Set the URI and TCP port appropriate for the given server type.

Parameters:

serverType - The type of API server.

Valid server types are:

• NaServer.SERVER_TYPE_FILER - For connecting to Data ONTAP storage systems.
• NaServer.SERVER_TYPE_DFM - For connecting to OnCommand Unified Manager server 5.2 or earlier.
• NaServer.SERVER_TYPE_OCUM - For connecting to OnCommand Unified Manager server 6.0 or later.

The default server type on NaServer construction is SERVER_TYPE_FILER.

Throws:

java.lang.IllegalArgumentException - if server type is not valid.

getTransportType

public int getTransportType()

Get the transport type, which is one of the TRANSPORT_TYPE_ values.

setTransportType

public void setTransportType(int transportType)

Set the transport type.

After setting the transport type, call the setPort() to set the port number used for that transport type.

Parameters:

transportType - The type of transport.

Valid transport types are:

• NaServer.TRANSPORT_TYPE_HTTP
• NaServer.TRANSPORT_TYPE_HTTPS

TRANSPORT_TYPE_HTTP is the default transport type for SERVER_TYPE_FILER and SERVER_TYPE_DFM. For SERVER_TYPE_OCUM, TRANSPORT_TYPE_HTTPS is the only supported transport type and is set by default.

Throws:

java.lang.IllegalArgumentException - if transport is not valid.

setAdminUser

public void setAdminUser(java.lang.String login,
                         java.lang.String password)

Set the login and password used for authenticating when an API is invoked.

Parameters:

login - The login name (often "root").

password - The password.

setStyle

public void setStyle(int style)

Set the authentication style for subsequent API authentications.

Parameters:

style - The style, must be one of: NaServer.STYLE_LOGIN_PASSWORD NaServer.STYLE_HOSTSEQUIV NaServer.STYLE_CERTIFICATE NaServer.STYLE_RPC

NaServer.STYLE_RPC and NaServer.STYLE_HOSTSEQUIV styles are applicable for Data ONTAP APIs only.

NaServer.STYLE_CERTIFICATE is currently applicable for DataFabric Manager server API communication only.

If style = NaServer.STYLE_CERTIFICATE, you can use certificates to authenticate clients who attempt to connect to a server without the need of username and password. This style will internally set the transport type to HTTPS (TRANSPORT_TYPE_HTTPS).

Verification of the server's certificate is required in order to properly authenticate the identity of the server. Server certificate (with hostname) verification will be enabled by default using this style.

You can disable server certificate (with hostname) verification using disableServerCertVerification() and and you can disable only hostname verification using disableHostnameVerification().

You can use setKeyStore() to specify the keystore containing client certificates and setTrustStore() to specify the truststore containing the certificates of the trusted Certificate Authorities required for authenticating the server.

Throws:

java.lang.IllegalArgumentException - if style is not valid.

setSnoop

public void setSnoop(int level)

Set the snoop (debugging) level.

Parameters:

level - 0 (the default) means no debugging. -1 means to print the raw XML input and output.

getStyle

public int getStyle()

Get the current authentication style.

Returns:

Integer value (possible values: NaServer.STYLE_LOGIN_PASSWORD, NaServer.STYLE_HOSTSEQUIV, NaServer.STYLE_RPC)

invokeElem

public NaElement invokeElem(NaElement xi)
                     throws java.io.IOException,
                            NaAuthenticationException,
                            NaAPIFailedException,
                            NaProtocolException

Invoke a single API request.

Parameters:

xi - The API element.

Returns:

Output results of the API.

Throws:

java.io.IOException - if there is a communication problem

NaAuthenticationException - if the login was not accepted

NaAPIFailedException - if the server returned a failure result.

NaProtocolException - if there is a protocol problem

invokeElemForXML

public java.lang.String invokeElemForXML(NaElement xi)
                                  throws java.io.IOException,
                                         NaAuthenticationException,
                                         NaAPIFailedException,
                                         NaProtocolException

Invoke a single ONTAPI API.

Parameters:

xi - The API element.

Returns:

Output results of the API in XML format.

Throws:

java.io.IOException

NaAuthenticationException

NaAPIFailedException

NaProtocolException

getXMLParseInput

public NaElement getXMLParseInput(java.lang.String args)
                           throws java.io.IOException,
                                  org.xml.sax.SAXException,
                                  NaProtocolException

Parses the given API request in the form of XML and builds an NaElement of it.

Parameters:

args - XML input string

Returns:

NaElement of the API request.

Throws:

java.io.IOException

org.xml.sax.SAXException

NaProtocolException

toString

public java.lang.String toString()

setVfilerTunneling

public void setVfilerTunneling(java.lang.String vfiler)

Set the name of the vfiler on which the Data ONTAP API commands need to be invoked.

setCookie

public void setCookie(java.lang.String cookieValue)

Adds a cookie header to the outgoing HTTP request. This menthod is used by NetApp's internal products.

Parameters:

cookieValue - Value of the cookie header

getCookie

public java.lang.String getCookie()

Gets the cookie header that will be added to the outgoing HTTP request. This menthod is used by NetApp's internal products.

Returns:

Value of the cookie header

setVserver

public void setVserver(java.lang.String vserver)

Sets the name of the vserver to which a Cluster API need to be tunneled from a Cluster Management Interface.

Parameters:

vserver - The name of the vserver.

getVserver

public java.lang.String getVserver()

Gets the name of the vserver to which a Cluster API need to be tunneled from a Cluster Management Interface.

Returns:

name of the vserver

setKeyStore

public void setKeyStore(java.lang.String keyStore,
                        java.lang.String keyStorePasswd)

Sets the location of the keystore file where the client certificate and the key reside.

Parameters:

keyStore - The location of the keystore file.

keyStorePasswd - The password to access the keystore file.

Throws:

java.lang.IllegalArgumentException - if keyStore is null.

setKeyStore

public void setKeyStore(java.lang.String keyStore,
                        java.lang.String keyStorePasswd,
                        java.lang.String keyPasswd)

Sets the location of the keystore file where the client certificate and the key reside.

Parameters:

keyStore - The location of the keystore file.

keyStorePasswd - The password to access the keystore file.

keyPasswd - The password to access the individual key in the keystore file. This is used if the key in the keystore file have a different password than the keystore file.

Throws:

java.lang.IllegalArgumentException - if keyStore is null.

setKeyStoreType

public void setKeyStoreType(int keyStoreType)

Sets the keystore type for client certificates.

Parameters:

keyStoreType - The type of the keystore file. Should be one of the NaServer.KEYSTORE_TYPE_* values.
The default type is KEYSTORE_TYPE_JKS (Java Key Store).

Throws:

java.lang.IllegalArgumentException - if keyStoreType is invalid.

enableServerCertVerification

public void enableServerCertVerification()

Enables the server certificate verification by the client. This method will internally enable hostname verification. The server certificate verification is enabled by default when the authentication style is set to STYLE_CERTIFICATE.

Use setTrustStore() method to specify the truststore containing the certificates of the trusted Certificate Authorities required for authenticating the server. You can disable hostname verification using disableHostnameVerification().

You need to set the transport type to HTTPS (TRANSPORT_TYPE_HTTPS) before calling this method.

Throws:

java.lang.IllegalStateException - if transport type is not set to HTTPS.

disableServerCertVerification

public void disableServerCertVerification()

Disables the server certificate verification by the client. This method will internally disable hostname verification.

You need to set the transport type to HTTPS (TRANSPORT_TYPE_HTTPS) before calling this method.

Throws:

java.lang.IllegalStateException - if transport type is not set to HTTPS.

isServerCertVerificationEnabled

public boolean isServerCertVerificationEnabled()

Determines whether Server certificate verification is enabled by the client.

enableHostnameVerification

public void enableHostnameVerification()

Enables Hostname verification by the client during server certificate verification. Hostname verification is enabled by default when the authentication style is set to STYLE_CERTIFICATE.

Hostname verification ensures that the hostname to which the client connects matches the hostname (CN name) in the certificate that the server sends back as part of the SSL connection.

For hostname verification, the application must specify the hostname (CN name) instead of the IP address it is connecting to the server in NaServer constructor.

Server certificate verification must be enabled before using this method.

Throws:

java.lang.IllegalStateException - if server certificate verification is not enabled.

disableHostnameVerification

public void disableHostnameVerification()

Disables Hostname verification by the client during server certificate verification.

Throws:

java.lang.IllegalStateException - if server certificate verification is not enabled.

isHostnameVerificationEnabled

public boolean isHostnameVerificationEnabled()

Determines whether Hostname verification is enabled by the client during server certificate verification.

setTrustStore

public void setTrustStore(java.lang.String trustStore)

Sets the default location of the truststore containing the certificates of the trusted Certificate Authorities required for authenticating the server.

Parameters:

trustStore - The location of the truststore file.

Throws:

java.lang.IllegalArgumentException - if trustStore is null.

enableTLS

public void enableTLS()

Enables TLS protocol for use on connection over HTTPS Transport. By default, TLS protocol is enabled.

disableTLS

public void disableTLS()

Disables TLS protocol for use over HTTPS Transport. By default, TLS protocol is enabled.

isTLSEnabled

public boolean isTLSEnabled()

Determines whether TLS protocol is enabled for use over HTTPS Transport.

enableSSLv3

public void enableSSLv3()

Enables SSLv3 protocol for use over HTTPS Transport. By default, SSLv3 protocol is disabled.

disableSSLv3

public void disableSSLv3()

Disables SSLv3 protocol for use over HTTPS Transport. By default, SSLv3 protocol is disabled.

isSSLv3Enabled

public boolean isSSLv3Enabled()

Determines whether SSLv3 protocol is enabled for use over HTTPS Transport.

setApplicationName

public static void setApplicationName(java.lang.String appName)

Sets the name of the client application.

Parameters:

appName - Client application name

getApplicationName

public static java.lang.String getApplicationName()

Returns the name of the client application.

Returns:

Name of the client application