com.canto.cumulus

Class Server

java.lang.Object

com.canto.cumulus.Server

public final class Server
extends java.lang.Object

The Server object allows you to connect to a remote server and administer or work with it.

Since:

1.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Server.CatalogInfo This immutable class holds information about a catalog at the server.

Method Summary

Methods

Modifier and Type	Method and Description
int	addExistingCatalog(GUID selector, java.lang.String dbSpec) Add an existing catalog to the Cumulus server.
int	addNewCatalog(GUID selector, java.lang.String dbSpec) Create a new catalog and add it to the Cumulus server.
int	addNewCatalog(GUID selector, java.lang.String dbSpec, java.lang.String catalogTemplate) Create a new catalog from the given template and add it to the Cumulus server.
void	changePassword(java.lang.String oldPassword, java.lang.String newPassword) Changes the current user password.
static void	changePassword(java.lang.String server, java.lang.String user, java.lang.String oldPassword, java.lang.String newPassword) Changes a user password.
boolean	equals(java.lang.Object o) Compares this server to the specified object.
int	findCatalogID(JPack catalogReference) Fidn a catalog at the server by providing the catalog reference data and return the catalog ID.
int	findCatalogID(java.lang.String catalogName) Find a catalog by name at the server.
int	findCatalogIDByLocation(java.lang.String catalogLocation) Fidn a catalog at the server by providing the catalog location string and return the catalog ID.
java.util.List<java.lang.String>	findCollections(java.lang.String queryString, java.util.List<SortFieldDescriptor> sortFields, java.util.Locale locale) Perform a search on all available collections and return a list of internal collection names.
static java.util.Set<java.net.SocketAddress>	findServer(int timeout) Return a set of SocketAddress instances that represent the currently running Cumulus server.
ItemCollection	getAllVocabulariesItemCollection() Returns an ItemCollection containing all items of the $Vocabulary catalog.
java.util.Map<java.lang.String,java.lang.String>	getBaseWebURLs() Get a list of all configured web publishing URLs for this server.
java.util.Set<java.util.Properties.BaseWebURL>	getBaseWebURLsProperties() Get a list of all configured web publishing URLs for this server.
java.lang.String	getCatalogDescription(int catalogID, int languageID) Return the user readable description for the given catalog.
java.lang.String	getCatalogDisplayName(int catalogID, int languageID) Return the user readable display name for the given catalog.
java.util.Set<java.lang.Integer>	getCatalogIDs(boolean sharedOnly, boolean publishedToInternetOnly) Get the IDs of all catalogs that are accessible to the current user.
Server.CatalogInfo	getCatalogInfo(int catalogID) Get Information about a given catalog at the server.
Server.CatalogInfo	getCatalogInfo(int catalogID, int languageID) Get Information about a given catalog at the server.
java.util.Set<java.lang.String>	getCollectionNames() Get the names of all server-side collections.
CumulusSession	getCumulusSession() Returns the current CumulusSession object
java.lang.Object	getParent() Returns the parent object of this server.
java.lang.String	getServerAddress() Returns the address of the machine this Server is located at.
int	getServerVersion() Returns the product version of this Server.
ServerStatistics	getStatistics() Get a statistic about the server.
int	hashCode() Returns a hash code value for the object.
boolean	isAlive() Check whether the server is still active and is processing requests.
MultiCategoryItemCollection	newMultiCategoryItemCollection() Create a new MultiCategoryItemCollection for the given table.
MultiItemCollection	newMultiItemCollection(java.lang.String tableName) Create a new MultiItemCollection for the given table.
MultiRecordItemCollection	newMultiRecordItemCollection() Create a new MultiRecordItemCollection for the given table.
ItemCollection	newStatisticsItemCollection(java.lang.String query, java.util.Locale locale) Create a new ItemCollection and fill it with the items found by the given query.
Catalog	openCatalog(int catalogID) Open a catalog of the server.
static Server	openConnection(boolean bWriteAccess, java.lang.String server, java.lang.String user, java.lang.String password) Connects to a Cumulus server using the default licensing.
static Server	openConnection(java.lang.String sSerialNumber, boolean bWriteAccess, java.lang.String server, java.lang.String user, java.lang.String password) Connects to a Cumulus server using a custom serial number.
static Server	openConnectionAs(boolean bWriteAccess, java.lang.String server, java.lang.String userToRunAs, java.lang.String user, java.lang.String password) Connects to a Cumulus server using the default licensing and allows to take the identity of another user.
static Server	openConnectionAs(java.lang.String sSerialNumber, boolean bWriteAccess, java.lang.String server, java.lang.String userToRunAs, java.lang.String user, java.lang.String password) Connects to a Cumulus server using a custom serial number taking identity of a specified user.
MultiRecordItemCollection	openMultiRecordItemCollection(java.lang.String collectionSetName) Open a server-side collection into a newly created MultiRecordItemCollection.
void	removeCatalog(int catalogID, int timeout, java.lang.String message) Remove a catalog from the Cumulus server.
byte[]	sendServerModuleMessage(java.lang.String module, byte[] inData) Sends a message with parameters to a server plug-in module (Administrator only).
void	setSharing(int catalogID, boolean shared, boolean publishedToInternet) Enable or disable sharing this catalog to other users.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

openConnection

public static Server openConnection(boolean bWriteAccess,
                    java.lang.String server,
                    java.lang.String user,
                    java.lang.String password)
                             throws LoginFailedException,
                                    PasswordExpiredException,
                                    ServerNotFoundException,
                                    CumulusException

Connects to a Cumulus server using the default licensing. Depending on the value of bWriteAccess the Cumulus server needs a valid runtime serial number in order to allow connecting:

• Toolbox Runtime RO for read-only access (bWriteAccess = false).
• Toolbox Runtime RW for read-write access (bWriteAccess = true ).

For example:

 // Connect to server "serverIP", default port as guest (read-only access)
 Server myServer = Server.openConnection(false, "serverIP", null, null);
 or
 // Connect to server "serverIP", port 3245 as user "John"
 // with password "abcdefg" (read-write access)
 Server myServer = Server.openConnection(true, "serverIP:3245", "John", "abcdefg");
 

Parameters:

bWriteAccess - use true if you may modify a catalog from this server (read-write access). Use false otherwise (read-only access).

server - the Cumulus server's address. If you want to deviate from the last TCP port number used, you can add a special server port number, separated by a colon ":".

user - the user name (use an empty string or null to connect as guest).

password - the user password (use an empty string or null to connect as guest).

Returns:

a server object.

Throws:

CumulusException - if the connection to the server cannot be established.

LoginFailedException - for a invalid combination of user name and password

PasswordExpiredException - when the password has expired and need to be changed

ServerNotFoundException - when no server is available at the given address

openConnectionAs

public static Server openConnectionAs(boolean bWriteAccess,
                      java.lang.String server,
                      java.lang.String userToRunAs,
                      java.lang.String user,
                      java.lang.String password)
                               throws LoginFailedException,
                                      PasswordExpiredException,
                                      ServerNotFoundException,
                                      CumulusException

Connects to a Cumulus server using the default licensing and allows to take the identity of another user. Depending on the value of bWriteAccess the Cumulus server needs a valid runtime serial number in order to allow connecting:

• Toolbox Runtime RO for read-only access (bWriteAccess = false).
• Toolbox Runtime RW for read-write access (bWriteAccess = true ).

For example:

 // Connect to server "serverIP", default port, taking identity of user peter, but authenticating as user mary
 Server myServer = Server.openConnectionAs (false, "serverIP", "peter", "mary", "mary's password");
 

Parameters:

bWriteAccess - use true if you may modify a catalog from this server (read-write access). Use false otherwise (read-only access).

server - the Cumulus server's address. If you want to deviate from the last TCP port number used, you can add a special server port number, separated by a colon ":".

userToRunAs - the user you want to run as

user - the user name of the user with the permission to run as some other user.

password - the user password.

Returns:

a server object.

Throws:

CumulusException - if the connection to the server cannot be established.

LoginFailedException - for a invalid combination of user name and password

PasswordExpiredException - when the password has expired and need to be changed

ServerNotFoundException - when no server is available at the given address

Since:

9.0

openConnection

public static Server openConnection(java.lang.String sSerialNumber,
                    boolean bWriteAccess,
                    java.lang.String server,
                    java.lang.String user,
                    java.lang.String password)
                             throws LoginFailedException,
                                    ServerNotFoundException,
                                    PasswordExpiredException,
                                    CumulusException

Connects to a Cumulus server using a custom serial number. A custom serial number needs a corresponding custom runtime serial number at the Cumulus server. It is recommended to use the other openConnection() method to use the default runtime serial numbers.

Parameters:

sSerialNumber - the serial number to use for connecting. You can use the standard Cumulus.READ_ONLY_SERIAL_NUMBER or Cumulus.READ_WRITE_SERIAL_NUMBER or provide a custom serial number. The Cumulus server needs a valid corresponding serial number to allow connecting.

bWriteAccess - use true if you may modify a catalog from this server. Use false otherwise.

server - the Cumulus server's address. If you want to deviate from the last TCP port number used, you can add a special server port number, separated by a colon ":".

user - the user name (use an empty string or null to connect as guest).

password - the user password (use an empty string or null to connect as guest).

Returns:

a server object.

Throws:

CumulusException - if the connection to the server cannot be established.

LoginFailedException - for a invalid combination of user name and password

PasswordExpiredException - when the password has expired and need to be changed

ServerNotFoundException - when no server is available at the given address

See Also:

openConnection(boolean, String, String, String), Cumulus.READ_ONLY_SERIAL_NUMBER, Cumulus.READ_WRITE_SERIAL_NUMBER

openConnectionAs

public static Server openConnectionAs(java.lang.String sSerialNumber,
                      boolean bWriteAccess,
                      java.lang.String server,
                      java.lang.String userToRunAs,
                      java.lang.String user,
                      java.lang.String password)
                               throws LoginFailedException,
                                      ServerNotFoundException,
                                      PasswordExpiredException,
                                      CumulusException

Connects to a Cumulus server using a custom serial number taking identity of a specified user. A custom serial number needs a corresponding custom runtime serial number at the Cumulus server. It is recommended to use the other openConnection() method to use the default runtime serial numbers.

Parameters:

sSerialNumber - the serial number to use for connecting. You can use the standard Cumulus.READ_ONLY_SERIAL_NUMBER or Cumulus.READ_WRITE_SERIAL_NUMBER or provide a custom serial number. The Cumulus server needs a valid corresponding serial number to allow connecting.

bWriteAccess - use true if you may modify a catalog from this server. Use false otherwise.

server - the Cumulus server's address. If you want to deviate from the last TCP port number used, you can add a special server port number, separated by a colon ":".

userToRunAs - the user you want to run as

user - the user name

password - the user password

Returns:

a server object.

Throws:

CumulusException - if the connection to the server cannot be established.

LoginFailedException - for a invalid combination of user name and password

PasswordExpiredException - when the password has expired and need to be changed

ServerNotFoundException - when no server is available at the given address

Since:

9.0

See Also:

openConnection(boolean, String, String, String), Cumulus.READ_ONLY_SERIAL_NUMBER, Cumulus.READ_WRITE_SERIAL_NUMBER

getCumulusSession

public CumulusSession getCumulusSession()

Returns the current CumulusSession object

Returns:

the current CumulusSession object.

getServerAddress

public java.lang.String getServerAddress()

Returns the address of the machine this Server is located at.

Returns:

server name used when connecting this Server instance

getServerVersion

public int getServerVersion()

Returns the product version of this Server.

Since:

11.1

isAlive

public boolean isAlive()

Check whether the server is still active and is processing requests.

Returns:

true if the server is still active, false otherwise.

Since:

7.0

getCatalogIDs

public java.util.Set<java.lang.Integer> getCatalogIDs(boolean sharedOnly,
                                             boolean publishedToInternetOnly)

Get the IDs of all catalogs that are accessible to the current user.

Parameters:

sharedOnly - Only return IDs of shared catalogs. For a non admin user this flag has no effect as he is allowed to access only shared catalogs anyway.

publishedToInternetOnly - Only return IDs of catalogs that are published to the Internet.

Returns:

The IDs of all accessible catalogs at the server.

Since:

8.0

getCatalogInfo

public Server.CatalogInfo getCatalogInfo(int catalogID)
                                  throws CumulusException

Get Information about a given catalog at the server.

Parameters:

catalogID - The ID of the requested catalog

Returns:

Information about the given catalog.

Throws:

CumulusException - in case of an error

Since:

8.0

getCatalogInfo

public Server.CatalogInfo getCatalogInfo(int catalogID,
                                int languageID)
                                  throws CumulusException

Get Information about a given catalog at the server.

Parameters:

catalogID - The ID of the requested catalog

Returns:

Information about the given catalog.

Throws:

CumulusException - in case of an error

Since:

9.0

getCatalogDescription

public java.lang.String getCatalogDescription(int catalogID,
                                     int languageID)
                                       throws CumulusException

Return the user readable description for the given catalog.

Parameters:

catalogID - The ID of the requested catalog

languageID - The language in which to return the description.

Returns:

A descriptive string for the given catalog.

Throws:

CumulusException - in case of an error

Since:

8.0

getCatalogDisplayName

public java.lang.String getCatalogDisplayName(int catalogID,
                                     int languageID)
                                       throws CumulusException

Return the user readable display name for the given catalog.

Parameters:

catalogID - The ID of the requested catalog

languageID - The language in which to return the display name.

Returns:

A descriptive name for the given catalog.

Throws:

CumulusException - in case of an error

Since:

8.5

setSharing

public void setSharing(int catalogID,
              boolean shared,
              boolean publishedToInternet)
                throws PermissionDeniedException,
                       CumulusException

Enable or disable sharing this catalog to other users. This can only be called by the Cumulus administrator.

Parameters:

catalogID - The ID of the requested catalog

shared - Flag indicating whether to enable or disable sharing.

publishedToInternet - Flag indicating whether to enable or disable publishing this catalog to the Internet.

Throws:

CumulusException - in case of an error

PermissionDeniedException

Since:

8.0

findCatalogID

public int findCatalogID(java.lang.String catalogName)
                  throws CumulusException

Find a catalog by name at the server.

Parameters:

catalogName - The name of the catalog to find

Returns:

The ID of the catalog if found.

Throws:

CumulusException - if the catalog can not be found

Since:

8.0

findCatalogID

public int findCatalogID(JPack catalogReference)
                  throws CumulusException

Fidn a catalog at the server by providing the catalog reference data and return the catalog ID.

Parameters:

catalogReference - the reference package for the requested catalog

Returns:

The ID of the catalog if found.

Throws:

CumulusException - if the catalog can not be found

Since:

8.0

See Also:

Catalog.getCatalogReference()

findCatalogIDByLocation

public int findCatalogIDByLocation(java.lang.String catalogLocation)

Fidn a catalog at the server by providing the catalog location string and return the catalog ID.

Parameters:

catalogLocation - The catalog location. This is the file path on the Cumulus server system.

Returns:

The ID of the catalog if found.

Since:

8.0

See Also:

Catalog.getLocation()

openCatalog

public Catalog openCatalog(int catalogID)

Open a catalog of the server. This is the only way to open a catalog. If you only know the name of the catalog use findCatalogID(String) to get the catalog ID.

Parameters:

catalogID - The ID of the catalog at the server. This ID uniquely identifies a catalog at the server but can change after a server restart.

Returns:

The open catalog.

Since:

8.0

See Also:

findCatalogID(String), findCatalogID(com.canto.cumulus.utils.JPack), findCatalogIDByLocation(String)

newMultiItemCollection

public MultiItemCollection newMultiItemCollection(java.lang.String tableName)
                                           throws CumulusException

Create a new MultiItemCollection for the given table. You should close the collection using MultiItemCollection.close() when you are done with it to release all resources and connections to the server. The MultiItemCollection returned is bound to this server and table so you can only add ItemCollections that belong to the same server and table inside a catalog.

Parameters:

tableName - The name of the table to create a MultiItemCollection for. You can pass one the predefined table names Cumulus.TABLE_NAME_ASSET_RECORDS or Cumulus.TABLE_NAME_CATEGORIES or the name of the table for a table field in one of these tables.

Returns:

A newly created MultiItemCollection

Throws:

CumulusException - in case of an error

Since:

8.0

See Also:

newMultiRecordItemCollection(), newMultiCategoryItemCollection()

newMultiRecordItemCollection

public MultiRecordItemCollection newMultiRecordItemCollection()

Create a new MultiRecordItemCollection for the given table. You should close the collection using MultiItemCollection.close() when you are done with it to release all resources and connections to the server. The MultiRecordItemCollection returned is bound to this server so you can only add RecordItemCollections that belong to the same server.

Returns:

A newly created MultiRecordItemCollection

Throws:

CumulusException - in case of an error

Since:

8.0

newMultiCategoryItemCollection

public MultiCategoryItemCollection newMultiCategoryItemCollection()

Create a new MultiCategoryItemCollection for the given table. You should close the collection using MultiItemCollection.close() when you are done with it to release all resources and connections to the server. The MultiCategoryItemCollection returned is bound to this server so you can only add CategoryItemCollections that belong to the same server.

Returns:

A newly created MultiCategoryItemCollection

Throws:

CumulusException - in case of an error

Since:

8.0

changePassword

public void changePassword(java.lang.String oldPassword,
                  java.lang.String newPassword)
                    throws CumulusException

Changes the current user password.

Parameters:

oldPassword - the user old password.

newPassword - the user new password.

Throws:

CumulusException - if the password cannot be changed.

changePassword

public static void changePassword(java.lang.String server,
                  java.lang.String user,
                  java.lang.String oldPassword,
                  java.lang.String newPassword)
                           throws CumulusException

Changes a user password.

Parameters:

server - the server name.

user - the user name.

oldPassword - the users old password.

newPassword - the users new password.

Throws:

CumulusException - if the password cannot be changed.

sendServerModuleMessage

public byte[] sendServerModuleMessage(java.lang.String module,
                             byte[] inData)
                               throws CumulusException

Sends a message with parameters to a server plug-in module (Administrator only). See the documentation of the corresponding server module for a description of the messages, parameters and reply structures.

Parameters:

module - the name or GUID as String of the server module.

inData - the message data to send to the module.

Returns:

the server module reply data.

Throws:

CumulusException - if the message cannot be sent.

Since:

8.0

addNewCatalog

public int addNewCatalog(GUID selector,
                java.lang.String dbSpec)
                  throws CumulusException

Create a new catalog and add it to the Cumulus server.

Parameters:

selector - The GUID of the database engine module at the server. Pass GUID.UID_SELECTOR_CUE for the Cumulus Database engine.

dbSpec - The location string for the catalog. For the Cumulus database engine pass the path to the catalog file at the server system.

Returns:

The ID of the newly created catalog.

Throws:

CumulusException - on error

Since:

8.0

See Also:

openCatalog(int)

addNewCatalog

public int addNewCatalog(GUID selector,
                java.lang.String dbSpec,
                java.lang.String catalogTemplate)
                  throws CumulusException

Create a new catalog from the given template and add it to the Cumulus server.

Parameters:

selector - The GUID of the database engine module at the server. Pass GUID.UID_SELECTOR_CUE for the Cumulus Database engine.

dbSpec - The location string for the catalog. For the Cumulus database engine pass the path to the catalog file at the server system.

catalogTemplate - the template to use for the new catalog

Returns:

The ID of the newly created catalog.

Throws:

CumulusException - on error

Since:

8.5.1

See Also:

openCatalog(int)

addExistingCatalog

public int addExistingCatalog(GUID selector,
                     java.lang.String dbSpec)
                       throws CumulusException

Add an existing catalog to the Cumulus server.

Parameters:

selector - The GUID of the database engine module at the server. Pass GUID.UID_SELECTOR_CUE for the Cumulus Database engine.

dbSpec - The location string for the catalog. For the Cumulus database engine pass the path to the catalog file at the server system.

Returns:

The ID of the catalog added to the server.

Throws:

CumulusException - on error

Since:

8.0

removeCatalog

public void removeCatalog(int catalogID,
                 int timeout,
                 java.lang.String message)
                   throws CumulusException

Remove a catalog from the Cumulus server.

Parameters:

catalogID - The ID of the catalog at the server.

timeout - The number of seconds to wait until all clients have closed their catalog connections.

message - The message being displayed at each client that has this catalog open.

Throws:

CumulusException - on error

Since:

8.0

getBaseWebURLs

public java.util.Map<java.lang.String,java.lang.String> getBaseWebURLs()

Get a list of all configured web publishing URLs for this server. These are modified using the ServerConsole Remote Admin settings "Base URLs for Web Access"

Returns:

A map of the web URLs using the name as the key and the URL as the value in the map.

Since:

8.0

getStatistics

public ServerStatistics getStatistics()

Get a statistic about the server.

Returns:

the server statistics

Since:

10.2.3

getBaseWebURLsProperties

public java.util.Set<java.util.Properties.BaseWebURL> getBaseWebURLsProperties()

Get a list of all configured web publishing URLs for this server. These are modified using the ServerConsole Remote Admin settings "Base URLs for Web Access"

Returns:

A set of the web URLs.

Since:

10.0.1

getParent

public java.lang.Object getParent()

Returns the parent object of this server.

Returns:

the CumulusSession to which this server belongs.

Since:

6.0

equals

public boolean equals(java.lang.Object o)

Compares this server to the specified object. The result is true if and only if the argument is not null and is a Server object that represents the same server as this object.

Overrides:

equals in class java.lang.Object

Parameters:

o - the object to compare

Returns:

true if the servers are equal; false otherwise.

hashCode

public int hashCode()

Returns a hash code value for the object.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for the object.

openMultiRecordItemCollection

public MultiRecordItemCollection openMultiRecordItemCollection(java.lang.String collectionSetName)
                                                        throws CumulusException

Open a server-side collection into a newly created MultiRecordItemCollection.

Parameters:

collectionSetName - The name of the collection at the server.

Returns:

A newly created MultiRecordItemCollection containing all record items of the collection.

Throws:

CumulusException - in case of an error

Since:

8.0

See Also:

getCollectionNames()

getCollectionNames

public java.util.Set<java.lang.String> getCollectionNames()

Get the names of all server-side collections.

Returns:

A collection of all collection names.

Since:

8.0

See Also:

openMultiRecordItemCollection(String)

findServer

public static java.util.Set<java.net.SocketAddress> findServer(int timeout)

Return a set of SocketAddress instances that represent the currently running Cumulus server.

Parameters:

timeout - the time in milliseconds to wait for answers

Returns:

set of SocketAddress instances

Since:

7.5

findCollections

public java.util.List<java.lang.String> findCollections(java.lang.String queryString,
                                               java.util.List<SortFieldDescriptor> sortFields,
                                               java.util.Locale locale)

Perform a search on all available collections and return a list of internal collection names.

Parameters:

queryString - A query string containing, Pass null

sortFields - The fields to sort by including whether to sort ascending or descending.

Returns:

A list of resulting collection names (internal names)

Since:

10.0

getAllVocabulariesItemCollection

public ItemCollection getAllVocabulariesItemCollection()

Returns an ItemCollection containing all items of the $Vocabulary catalog. This collection can't be used to search for items. Instead it can be used to access all vocabulary items.

Returns:

ItemCollection containing all items of the $Vocabulary catalog

Since:

10.0.2

newStatisticsItemCollection

public ItemCollection newStatisticsItemCollection(java.lang.String query,
                                         java.util.Locale locale)
                                           throws QueryParserException,
                                                  InvalidArgumentException,
                                                  CumulusException

Create a new ItemCollection and fill it with the items found by the given query.

Parameters:

query - The query string to execute to fill in the collection. An empty or null string returns an empty collection.

locale - The locale to use for parsing the query string

Returns:

A newly created ItemCollection

Throws:

InvalidArgumentException - on error finding values specified in the query string

CumulusException - on other errors

QueryParserException - on errors parsing the query string

Since:

10.0.2