CONSTRUCTOR statement

Defines a constructor for a class. A constructor is a special type of method that ABL invokes to initialize data for a new object of a class that is instantiated using the NEW function (classes), NEW statement, or DYNAMIC-NEW statement, or to initialize static members of a class.

Note: This statement is applicable only when used in a class definition (.cls) file.

Syntax


CONSTRUCTOR [ PRIVATE \| PROTECTED \| PUBLIC \| STATIC ] `class-name` ( [ `parameter` [ , `parameter` ] ... ] ) : `constructor-body`

[ PRIVATE | PROTECTED | PUBLIC | STATIC ]

Specifies the access mode for the constructor.

PRIVATE specifies an instance constructor that you can call explicitly within another constructor of the defining class (using the THIS-OBJECT statement) during class instantiation, or that a static method or static constructor of the class can invoke by executing the NEW function (classes) in order to allow the class to instantiate itself.

PROTECTED specifies an instance constructor that you can only call explicitly within a constructor of an immediately inheriting subclass (using the SUPER statement) during class instantiation.

PUBLIC specifies an instance constructor that you can call explicitly from within another constructor in the defining class during class instantiation, that you can call explicitly from within a constructor of an immediately inheriting subclass during class instantiation, and that you can call implicitly from any class or procedure when you instantiate the class.

STATIC specifies a static constructor that executes exactly once in an ABL session the first time you reference a class type that defines this constructor in its class hierarchy. You cannot invoke a static constructor in any other way or at any other time. You can define only one static constructor for a given class. If you do not define a static constructor, ABL defines a default static constructor to initialize the static members of a class.

The default access mode is PUBLIC.

class-name

The name of the class this method constructs. This name must match the class name portion of the type name for the class (that is, the name of the class definition file excluding the .cls extension and any package path information).

( [ parameter [ , parameter ] ... ] )

Optionally specifies one or more parameters of the constructor. Any instance constructor defined without a parameter list is the default instance constructor for the defining class. The parameter list for a defined static constructor must be empty.

If this instance constructor is one of several overloaded constructors defined for a class, the parameter list must be unique among all the other constructors. This uniqueness can be established using a different combination of number, data types, or modes for the parameters. For information on the parameter definition syntax and establishing uniqueness for overloaded constructors, see the Parameter definition syntax reference entry. Note that any defined static constructor does not participate in constructor overloading with instance constructors.

constructor-body

The body of the constructor definition. Define the constructor body using the following syntax:

Syntax
`constructor-logic` . . . END [ CONSTRUCTOR ].

constructor-logic

The logic of the constructor, which can contain any ABL statements currently allowed within a PROCEDURE block including class-related statements. These statements typically contain logic to initialize the data members and properties in the class.

Each logic statement must end with a period.

If you are defining an instance constructor, regardless of other statements in the constructor, the first action of the constructor must be a call to another instance constructor in the defining class or in the immediate super class. ABL can call a default super class constructor implicitly, or you can call a super class constructor or another overloaded constructor in the defining class explicitly as the first statement of a constructor. You cannot explicitly call another constructor in any other statement of a constructor, and you cannot call any defined static constructor.

If there is no constructor instance defined in the immediate super class and you do not explicitly invoke a constructor, ABL always implicitly invokes the built-in default super class constructor (without parameters) as the first action. If there is an instance constructor defined in the super class that does not take parameters, you also do not need to explicitly invoke an instance constructor. ABL implicitly invokes this user-defined default super class constructor. You only need to explicitly invoke another instance constructor when the super class has constructors defined for it and all of these constructors take parameters.

When you invoke an instance constructor that takes parameters, again, you must invoke that constructor as the first executable statement in the invoking constructor. If you want to invoke a super class instance constructor, you must invoke the SUPER statement with parameters that match the parameters of the super class constructor with respect to number, data type, and mode.

If you want to invoke an overloaded instance constructor of the defining class, you must invoke the THIS-OBJECT statement as the first statement, with parameters that match the parameters of the overloaded constructor with respect to number, data type, and mode. If you invoke an overloaded constructor, and that overloaded constructor does not invoke another overloaded constructor, it must invoke a super class constructor, either implicitly (the default) or explicitly as its first statement. So, in any chain of explicit calls from one overloaded constructor to another, the last overloaded constructor in the chain must invoke a super class constructor.

If you are defining a static constructor, you cannot access any instance members of a class (including the defining class), nor can you use the SUPER and THIS-OBJECT statements. From a static constructor, you can access only other static members of a class and the local variables or other local data elements of the constructor. A static constructor also cannot execute any input-blocking statements, such as UPDATE or WAIT-FOR.

END [ CONSTRUCTOR ]

Specifies the end of the constructor body definition. You must end the constructor body definition with the END statement.

Examples

The following example shows the definition of an instance constructor:

CONSTRUCTOR PUBLIC CustObj( ): m_NumCusts = 0. /* Fill a temp table and get the row count */ FOR EACH Customer NO-LOCK: CREATE ttCust. ASSIGN ttCust.CustNum = Customer.CustNum ttCust.Name = Customer.Name m_NumCusts = m_NumCusts + 1. END. END CONSTRUCTOR.

CONSTRUCTOR PUBLIC CustObj( ): 
  m_NumCusts = 0. 
  /* Fill a temp table and get the row count */ 
  FOR EACH Customer NO-LOCK: 
    CREATE ttCust. 
    ASSIGN 
      ttCust.CustNum = Customer.CustNum 
      ttCust.Name    = Customer.Name 
      m_NumCusts     = m_NumCusts + 1. 
  END. 
END CONSTRUCTOR.

For more examples of constructor definitions, including a static constructor and a constructor for an abstract class, see the descriptions of r-CustObj.cls, r-CustObjStatic.cls, and r-CustObjAbstract.cls in the CLASS statement reference entry.

Notes

You can terminate a CONSTRUCTOR statement with either a period (.) or a colon (:), but typically use a colon (:).

A constructor definition must begin with the CONSTRUCTOR statement and end with the END statement.

A constructor has no return type.

You never explicitly invoke an instance constructor to create a class instance. The constructor is implicitly invoked when you instantiate the defining class using the NEW function (classes), NEW statement, or DYNAMIC-NEW statement, passing any parameters required to identify the instantiating constructor. The instantiating constructor then directly or indirectly calls an instance constructor in its immediate super class, which similarly calls an instance constructor in its immediate super class, and so on for all classes in the class hierarchy, until the default instance constructor of the root (Progress.Lang.Object class) is called. From this point, the root constructor and all previously called instance constructors complete execution in reverse order of invocation, terminating class instantiation with completion of the initial instantiating constructor.

Within a class hierarchy, you can explicitly invoke an instance constructor from an instance constructor of an immediate subclass using the SUPER statement or from an overloaded constructor in the same defining class using the THIS-OBJECT statement. The invoking constructor must specify any parameters required to identify the called constructor. These parameters must match the constructor parameters with respect to the number, data type, and mode.

You never explicitly invoke a static constructor. All the static constructors of a class hierarchy with static members execute on first reference to a given class within an ABL session. This first reference causes the static constructors of all super classes in the referenced class hierarchy that have static members to execute from top to bottom, terminating with the execution of the static constructor for the most derived class with static members. For any single class with static members, its static constructor runs only once per ABL session or until after the given class is compiled again. If the first reference to a class occurs during class instantiation, this sequence of static constructor execution occurs prior to execution of the instantiating constructor. Thus, all static constructors in a class hierarchy are guaranteed to execute before a class instance is referenced.

Prior to execution of a given static constructor, all of the static data members and properties of the defining class are set to their initial values. The constructor then accesses these initial values of static members, as appropriate. This initialization of static members occurs only once per session or until the class is recompiled.

You can handle application errors in an instance constructor as in any ABL block. However, by executing a RETURN ERROR action at the block level or a THROW action at the block level with the presence of a ROUTINE-LEVEL ON ERROR UNDO, THROW statement, the AVM returns the ERROR condition from the constructor block. With this returned ERROR condition, ABL terminates creation of the object. If any part of the class hierarchy has been created (constructors executed), ABL executes the corresponding destructors for those classes automatically and raises ERROR on the statement that instantiated the class. If this constructor is invoked as part of a NEW statement or DYNAMIC-NEW statement, the data element set to receive an object reference to the failed class instantiation remains unchanged. If a RETURN ERROR also includes the option to return a character string value, or you set the ReturnValue property of a Progess.Lang.AppError object that you THROW, you can get this value using the RETURN-VALUE function following the statement that attempted to instantiate the class or in a CATCH block that catches the Progress.Lang.AppError object. For more information, see OpenEdge Development: Object-oriented Programming.

You can handle application errors in a static constructor similar to an instance constructor. However, an ERROR condition returned from the constructor block is raised on the statement whose class reference caused the static constructor to be invoked (whether or not the statement instantiates the class). With this ERROR condition, ABL fails to loaded the specified class and its entire class hierarchy. In addition, ABL does not load the specified class, or the other classes of its class hierarchy, for the remainder of the ABL session, or until the specified class is recompiled.