Creates an instance of a class (object) and
returns an object reference to that instance. You can use this object
reference to access the PUBLIC data members, properties, and methods
of the instance. For more information on object references, see
the reference entry for a Class-based object reference.
Syntax
NEW object-type-name ( [ parameter[ , parameter ]...] )
|
-
object-type-name
- Specifies the type name of the ABL or .NET class you want
to instantiate. Specify a class type name using the syntax as described
in the Type-name syntax reference
entry. If object-type-name specifies a .NET object,
it can be most any .NET class, with a few restrictions. For
more information, see the Notes of this reference entry. The value
of object-type-name is restricted to alphanumeric
characters plus the symbols #, $, %, and _.
If, without casting,
you assign the NEW function value to a target data element, or pass
the NEW function as input to a target routine parameter, object-type-name must
specify one of the following classes:
- The same class
type that is defined for the target
- A subclass of the class type that is defined for the target
- A class type that implements the interface type defined for
the target
If object-type-name specifies
one of the following kinds of object types, ABL raises a compiler
error:
- An interface type
- An abstract class type
- ( [
parameter[ ,
parameter
]...] )
- Specifies zero or more parameters passed to a PUBLIC instance constructor
that is defined for the class. You must provide the parameters identified
by the specified constructor, matched with respect to number, data
type, and mode. To invoke a constructor that is overloaded in the class,
you must specify sufficient information for each parameter to
disambiguate it from all other constructors in the class. Otherwise,
ABL raises an error identifying the ambiguity.
For information
on the parameter passing syntax and disambiguating overloaded constructors,
see the Parameter passing syntax reference entry.
For information on defining
a constructor for a class, see the CONSTRUCTOR statement reference entry.
Examples
The
following example shows how the NEW function can instantiate a class within
an expression:
DEFINE VARIABLE rObj AS Progress.Lang.Object.
IF ( NEW Progress.Lang.Object( ) ):ToString( ) BEGINS "Progress" THEN
MESSAGE "This object is making Progress..." VIEW-AS ALERT-BOX.
|
This code fragment instantiates a Progress.Lang.Object
in order to check if the string value returned from its ToString( )
method begins with "Progress", and displays a message if it does.
The
following example shows three (3) invocations of the NEW function.
r-newclass.p
ROUTINE-LEVEL ON ERROR UNDO, THROW.
FUNCTION ClassFunc RETURNS CLASS Progress.Lang.Object
(INPUT iVal AS INTEGER):
MESSAGE "iVal = " iVal VIEW-AS ALERT-BOX.
IF iVal MODULO 2 = 0 THEN
RETURN NEW Progress.Lang.Object( ).
ELSE
RETURN?.
END FUNCTION.
RUN DisplayClass( NEW Progress.Lang.Object( ) ).
PROCEDURE DisplayClass:
DEFINE INPUT PARAMETER rObj AS CLASS Progress.Lang.Object.
DEFINE VARIABLE cClass1 AS CHARACTER NO-UNDO.
DEFINE VARIABLE cClass2 AS CHARACTER NO-UNDO.
cClass1 = rObj:ToString( ).
/* The ToString( ) call errors on an odd RANDOM input value */
cClass2 = ( ClassFunc( RANDOM(1,100) ) ):ToString( ).
MESSAGE "The " cClass1 " and " cClass2 " instances have the same
class type."
VIEW-AS ALERT-BOX.
CATCH e AS Progress.Lang.SysError:
UNDO, THROW NEW Progress.Lang.AppError( "Application Error", 555 ).
END CATCH.
END PROCEDURE.
|
This r-newclass.p procedure
runs an internal procedure (DisplayClass) that
displays a message showing the ToString( ) values of two
different objects instantiated as the same class type (Progress.Lang.Object).
However, one of these objects is instantiated within a user-defined
function (ClassFunc) that returns a valid object
reference or the Unknown value (?) in order to generate
an error, depending on the input value of a RANDOM function.
When
a valid object reference is returned, it is used to access the ToString( ) method
of the instance in an expression. When the Unknown value (?) is
returned, this generates a run-time error when used as an object
reference. The procedure then catches the error and responds by throwing
a Progress.Lang.AppError object that is also instantiated by a NEW function
invoked in an expression, and the error text is displayed as an
error message when run in the OpenEdge Editor.
Notes
- When
you create an instance of a class, ABL invokes the specified constructor
for the class. At this time, the object instance gets its own copy of
the data members and properties defined in the class and in all
classes within its inherited class hierarchy. In addition, the object
instance is added to the session object chain referenced by the FIRST-OBJECT attribute or LAST-OBJECT attribute of
the SESSION system handle.
- The ABL Virtual Machine (AVM) automatically deletes (garbage collects)
any class instance that you create with the NEW function some time
after no reference to that object exists in the ABL session. However, you
can force any class instance to be deleted immediately by using
the DELETE OBJECT statement. For more information on garbage collection for
class instances, see the DELETE OBJECT statement reference entry.
- You can assign the object reference value returned by the NEW function to an ABL data
element (or target of a passed parameter) defined as a class type or interface type when
the destination data element (or parameter target) is defined as the same class as, as a
super class of, or as an interface implemented by the instantiated class. In any case, the
target data element retains its defined class or interface type. For more information on
assigning object references to ABL data elements, see the NEW statement and Assignment (=) statement reference entries.
- You can use an object reference as a parameter or return type
for methods, internal and external procedures, and user-defined
functions (see the example).
- You can pass an object reference as a parameter between an AppServer and
an ABL client, although there are restrictions on the types of object
you can pass. See the Parameter definition syntax entry for the full list of restrictions.
- You can pass a temp-table or ProDataSet containing an object
reference field as a parameter between an AppServer and an ABL
client, as long as the objects themselves satisfy the restrictions
described in the Parameter definition syntax entry.
- You can only access PRIVATE class members using an object reference
in instances of the class where the members are defined. Likewise, you
can only access PROTECTED class members using an object reference
in an instance of the class or subclass where the member is defined. To
allow access outside of these situations, you must provide PUBLIC methods
or properties to do so. For information on accessing data members,
properties, or methods using an object reference, see the Class-based object reference entry.
- Class-based object instances are not associated with handle-based objects,
such as socket or procedure objects, and object references are not compatible
with object handles. Thus, for example, you cannot use an object
reference in any statement or function that returns a value of type HANDLE,
and you cannot pass a procedure handle to a method that expects
an object reference.
- You can compare two object references for equality using the
EQ (=) operator, which determines if two object references are referencing
the same object instance. Two object references can be equal even
when you define their data types for different classes in the same
class hierarchy as long as they each point to the same class instance.
So, if ClassA is a super class of ClassB, and two object references
point to the same ClassB instance, if one object reference is defined
with the ClassA data type and the other object reference is defined
with the ClassB data type, the two object references are equal.
However, if the ClassA object reference points to a different class
instance than the ClassB object reference, the two object references
are not equal. Two object references are also equal if they are both
set to the Unknown value (?).
- You can use the Equals( ) method in the Progress.Lang.Object
class to compare the data members and properties of two object references,
as long as this class provides an implementation of the Equals( )
method.
- If object-type-name specifies a .NET object, note
that in ABL you cannot instantiate the following .NET classes:
- Any .NET class that is defined in the default namespace, that
is, where the class name is the complete object type name
- System.Threading.Thread or any class derived
from it
- System.Delegate or any delegate type derived
from it
- If object-type-name specifies a GUI or non-GUI .NET object
type, you can instantiate it within a non-GUI ABL session
on Windows, including a:
- Character mode (CHUI) client
- Batch-mode client
- AppServer agent session
- WebSpeed agent session
However, you cannot block
for any .NET object events or visualize any GUI objects in
a non-GUI ABL session.
- This function can raise errors during the execution of constructors
for the class being instantiated, or for any class in its inherited
class hierarchy. For example:
- A constructor in the class
hierarchy executes the RETURN statement with
the ERROR option or the UNDO statement with
the THROW or RETURN ERROR options.
- The class definition file for the class, a super class, or an
interface could not be found.
- The run-time parameters of the constructor for the class, or
a constructor for a class in the inherited class hierarchy, are
not compatible.
When the AVM encounters one of these
errors, and the constructor cannot create the class instance or
its inherited class hierarchy, the AVM automatically invokes the
destructor for any class that has already been constructed while
building the class hierarchy for the object.
For more information
on errors raised by instantiating classes, see OpenEdge Development:
Object-oriented Programming.
- Any errors returned during class instantiation, including application errors
returned by constructors executing RETURN ERROR or UNDO, THROW,
are handled by the statement that invokes the NEW function. In any
case, if a RETURN ERROR in the constructor of the instantiating class
also returns an optional character string value, this value is available using
the RETURN-VALUE function following the statement where this NEW
function appears.
See also
Assignment (=) statement, Class-based object reference, CLASS statement, CONSTRUCTOR statement, DELETE OBJECT statement, DYNAMIC-NEW statement, FIRST-OBJECT attribute, FUNCTION statement, LAST-OBJECT attribute, METHOD statement, New( ) method, NEW statement, Parameter passing syntax, Type-name syntax, USING statement