com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord > Class Template Referenceabstract

This is the representation of a symbol in GAMS. More...

Inherits Iterable< T >.

Public Member Functions

getFirstRecord ()
 Get the first record of GAMSSymbol. More...
 
getFirstRecord (String ... slice)
 Retrieve the first record in GAMSSymbol that meets the slice criteria. More...
 
getLastRecord ()
 Get the last record of GAMSSymbol. More...
 
getLastRecord (String ... slice)
 Retrieve the last record in GAMSSymbol that meets the slice criteria. More...
 
findRecord (String ... keys)
 Find record in GAMSSymbol. More...
 
addRecord (Vector< String > keys)
 Add record T to GAMSSymbol. More...
 
addRecord (String ... keys)
 Add record T to GAMSSymbol. More...
 
mergeRecord (String ... keys)
 Find record T with specified keys in GAMSSymbol. More...
 
boolean deleteRecord (String ... keys)
 Delete record T from GAMSSymbol. More...
 
boolean clear ()
 Clear symbol. More...
 
void compact ()
 
void copySymbol (GAMSSymbol<?> target)
 Copy all records of this GAMSSymbol to target GAMSSymbol (if target had records, they will be deleted) More...
 
GAMSDatabase getDatabase ()
 Get GAMSDatabase containing GAMSSymbol. More...
 
int getDimension ()
 Get GAMSSymbol dimension. More...
 
String getName ()
 Get GAMSSymbol name. More...
 
String getText ()
 Get GAMSSymbol explanatory text. More...
 
int getNumberOfRecords ()
 Get the number of records of the GAMSSymbol. More...
 
List< Object > getDomains ()
 Retrieve domains of Symbol, each element is either a GAMSSet (real domain) or a String (relaxed domain). More...
 
List< String > getDomainsAsStrings ()
 Retrieve domains of Symbol, each element is a string. More...
 
boolean checkDomains ()
 Check all GAMSSymbolRecord instances of the symbol if all their records are within the specified domain of the symbol. More...
 
List< GAMSSymbolDomainViolationgetSymbolDomainViolations (int maxNoViolation)
 Check all GAMSSymbolRecord instances in the Symbol if they are within the specified domain of the symbol. More...
 
Iterator< T > iterator ()
 Returns an iterator over a set of elements of type T. More...
 

Protected Member Functions

 GAMSSymbol (GAMSDatabase database, long sPtr)
 Create a GAMS Symbol instance. More...
 
 GAMSSymbol (GAMSDatabase database, String identifier, int dimension, String explanatoryText)
 Create a GAMS Symbol instance. More...
 
abstract T CheckAndReturnRecord (long symIterPtr)
 This method checks if symbol pointer is valid. More...
 

Detailed Description

This is the representation of a symbol in GAMS.

It exists in a GAMSDatabase and contains GAMSSymbolRecords which one can iterate through. Derived classes are GAMSEquation, GAMSParameter, GAMSSet and GAMSVariable.

Parameters
<T>GAMSSymbolRecord or its subclass
See also
GAMSDatabase
GAMSDatabaseIterator
GAMSSymbolIterator

Constructor & Destructor Documentation

◆ GAMSSymbol() [1/2]

com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.GAMSSymbol ( GAMSDatabase  database,
long  sPtr 
)
protected

Create a GAMS Symbol instance.

The constructor assumes that the GAMSDatabase instance is not disposed (resources are still available) and not record-locked (it is possible to update a record in GAMSDatabase instance).

Parameters
databaseGAMSDatabase instance
sPtrsymbol pointer
Exceptions
GAMSExceptionIf the GAMSDatabase instance of this symbol has already been disposed.

◆ GAMSSymbol() [2/2]

com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.GAMSSymbol ( GAMSDatabase  database,
String  identifier,
int  dimension,
String  explanatoryText 
)
protected

Create a GAMS Symbol instance.

The constructor assumes that the GAMSDatabase instance is not disposed (resources are still available) and

Parameters
databaseGAMSDatabase instance
identifiersymbol identifier
dimensionsymbol dimension
explanatoryTextsymbol explanatory text
Exceptions
GAMSExceptionIf the GAMSDatabase instance of this symbol has already been disposed.

Member Function Documentation

◆ addRecord() [1/2]

T com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.addRecord ( Vector< String >  keys)

Add record T to GAMSSymbol.

Parameters
keysList of keys. Null string is not a valid key.
Returns
Reference to the added record T
Exceptions
GAMSExceptionIf the GAMSSymbolRecord instance containing keys could not be successfully added, or the GAMSDatabase instance of this symbol has already been disposed.

◆ addRecord() [2/2]

T com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.addRecord ( String ...  keys)

Add record T to GAMSSymbol.

Parameters
keysArbitrary arguments of keys. Null string is not a valid key.
Returns
Reference to added record T
Exceptions
GAMSExceptionIf the GAMSSymbolRecord instance containing keys could not be successfully added, or the GAMSDatabase instance of this symbol has already been disposed.
See also
GAMSSymbol.deleteRecord(String...)
GAMSSymbol.findRecord(String...)
GAMSSymbol.mergeRecord(String...)

◆ CheckAndReturnRecord()

abstract T com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.CheckAndReturnRecord ( long  symIterPtr)
abstractprotected

This method checks if symbol pointer is valid.

If the pointer is valid then it returns an instance of of GAMSSymbolRecord containing symbol iteration pointer, otherwise it throws a GAMSException.

Parameters
symIterPtrsymbol iteration pointer
Returns
an instance of a subclass of GAMSSymbolRecord

◆ checkDomains()

boolean com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.checkDomains ( )

Check all GAMSSymbolRecord instances of the symbol if all their records are within the specified domain of the symbol.

Returns
true if every instance does not contain a domain violation, false otherwise.
Exceptions
GAMSExceptionIf GAMSDatabase instance of this symbol has already been disposed or there is an error checking the domain.
See also
GAMSDatabase.checkDomains()
GAMSDatabase.getDatabaseDomainViolations(int, int)
GAMSSymbol.getSymbolDomainViolations(int)

◆ clear()

boolean com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.clear ( )

Clear symbol.

Returns
True if cleared successfully, otherwise false
Exceptions
GAMSExceptionIf the instance could not be successfully cleared, or the GAMSDatabase instance of this symbol has already been disposed.

◆ compact()

void com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.compact ( )
Deprecated:
No longer available for public use, will be removed in the next version.

Dispose temporary external resources in database (advanced use)

Exceptions
GAMSExceptionIf the GAMSDatabase instance of this symbol has already been disposed.

◆ copySymbol()

void com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.copySymbol ( GAMSSymbol<?>  target)

Copy all records of this GAMSSymbol to target GAMSSymbol (if target had records, they will be deleted)

Parameters
targetTarget GAMSSymbol
Exceptions
GAMSExceptionIf the target symbol is contained in a record-locked database, or the GAMSDatabase instance of either this symbol or target symbol has already been disposed.

◆ deleteRecord()

boolean com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.deleteRecord ( String ...  keys)

Delete record T from GAMSSymbol.

In case GAMSSymbolRecord T has been successfully deleted, the iteration reference will be reseted as it is no longer possible to iterate to the next symbol using using reference of T.

Parameters
keysList of keys. Null string is not a valid key.
Returns
true if deleted successfully, otherwise false
Exceptions
GAMSExceptionIf the GAMSSymbolRecord instance containing the keys could not be deleted, or the GAMSDatabase instance of this symbol has already been disposed.
See also
GAMSSymbol.addRecord(String...)
GAMSSymbol.findRecord(String...)
GAMSSymbol.mergeRecord(String...)

◆ findRecord()

T com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.findRecord ( String ...  keys)

Find record in GAMSSymbol.

Parameters
keysList of keys. Null string is not a valid key.
Returns
Reference to found record
Exceptions
GAMSExceptionIf a GAMSSymbolRecord instance containing keys could not be found, or the GAMSDatabase instance of this symbol has already been disposed.

◆ getDatabase()

Get GAMSDatabase containing GAMSSymbol.

Returns
Reference to GAMSDatabse object

◆ getDimension()

int com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getDimension ( )

Get GAMSSymbol dimension.

Returns
the dimension of the GAMSSymbol

◆ getDomains()

List<Object> com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getDomains ( )

Retrieve domains of Symbol, each element is either a GAMSSet (real domain) or a String (relaxed domain).

Returns
domains of symbol as a list of objects (each object is either a GAMSSet or String)
Exceptions
GAMSExceptionIf this instance is a universe symbol with name "*"

◆ getDomainsAsStrings()

List<String> com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getDomainsAsStrings ( )

Retrieve domains of Symbol, each element is a string.

Note: If the domain is an alias in GAMS, this call will return the name of the alias, not the name of the aliased Set

Returns
domains of symbol as a list of String

◆ getFirstRecord() [1/2]

T com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getFirstRecord ( )

Get the first record of GAMSSymbol.

Returns
Reference to the first GAMSSymbolRecord
Exceptions
GAMSExceptionIf the database of this GAMSSymbol instance has already been disposed.

◆ getFirstRecord() [2/2]

T com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getFirstRecord ( String ...  slice)

Retrieve the first record in GAMSSymbol that meets the slice criteria.

For example:

   try {
       System.out.println("Transportation costs to chicago");
       String[] slice = new String[] {" ", "chicago"};
       GAMSParameter c = t1.OutDB().getParameter("c");
       GAMSParameterRecord x1 = c.getFirstRecord(slice);
       do {
           System.out.println("from "+x1.getKeys()[0]+" to "+ x1.getKeys()[1] + " : " + x1.getValue());
       } while(x1.moveNext());
   } catch (GAMSException e) {
       System.out.println("No records found");
   }
Parameters
sliceDefine filter for elements whose record should be retrieved
Returns
Reference to record
Exceptions
GAMSExceptionIf there is no record in this symbol specified by the slice or the GAMSDatabase instance of this symbol has already been disposed.
See also
GAMSSymbolRecord.moveNext()
GAMSSymbolRecord.movePrevious()

◆ getLastRecord() [1/2]

T com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getLastRecord ( )

Get the last record of GAMSSymbol.

Returns
Reference to the last GAMSSymbolRecord
Exceptions
GAMSExceptionIf there is no record in this symbol or the GAMSDatabase instance of this symbol has already been disposed.

◆ getLastRecord() [2/2]

T com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getLastRecord ( String ...  slice)

Retrieve the last record in GAMSSymbol that meets the slice criteria.

Parameters
sliceDefine filter for elements whose record should be retrieved
Returns
Reference to record
Exceptions
GAMSExceptionIf there is no record in this symbol specified by the slice or the GAMSDatabase instance of this symbol has already been disposed.
See also
GAMSSymbolRecord.moveNext()
GAMSSymbolRecord.movePrevious()

◆ getName()

String com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getName ( )

Get GAMSSymbol name.

Returns
the name of the GAMSSymbol

◆ getNumberOfRecords()

int com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getNumberOfRecords ( )

Get the number of records of the GAMSSymbol.

Returns
the number of records of the GAMSSymbol
Exceptions
GAMSExceptionIf the GAMSDatabase instance of this symbol has already been disposed.

◆ getSymbolDomainViolations()

List<GAMSSymbolDomainViolation> com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getSymbolDomainViolations ( int  maxNoViolation)

Check all GAMSSymbolRecord instances in the Symbol if they are within the specified domain of the symbol.

It returns a list of GAMSSymbolDomainViolation instances containing domain violation information for problematic records. Each GAMSSymbolDomainViolation instance contains information of which GAMSSymbolRecord instance whose domain is violated as well as a violation array of boolean value with the size of the GAMSSymbol instance dimension. The array position contains {true} value means there is a domain violation at the relative dimension, otherwise it contains {false} value.

Parameters
maxNoViolationThe maximum number of domain violation records which should be stored (0 for no limit)
Returns
a list of GAMSDatabaseDomainViolation containing a domain violation information for each symbol in a GAMSDatabase instance.
Exceptions
GAMSExceptionif there is an error checking domain violations
See also
GAMSDatabase.checkDomains()
GAMSDatabase.getDatabaseDomainViolations(int, int)
GAMSSymbol.checkDomains()

◆ getText()

String com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.getText ( )

Get GAMSSymbol explanatory text.

Returns
the name of the GAMSSymbol

◆ iterator()

Iterator<T> com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.iterator ( )

Returns an iterator over a set of elements of type T.

Returns
an iterator over a set of elements of type T.

◆ mergeRecord()

T com.gams.api.GAMSSymbol< T extends GAMSSymbolRecord >.mergeRecord ( String ...  keys)

Find record T with specified keys in GAMSSymbol.

In case the record is not found, the record with the specified keys will be added and returned the call.

Parameters
keysArbitrary arguments of keys. Null string is not a valid key.
Returns
Reference to record that is found or added
Exceptions
GAMSExceptionIf the record to be found has different dimensions than the specified key.
See also
GAMSSymbol.addRecord(String...)
GAMSSymbol.deleteRecord(String...)
GAMSSymbol.findRecord(String...)