create Instruction

The create instruction creates an instance of a class, and assigns it to a variable or a property.

Syntax

The syntax of the create instruction is:

create entity [as expression] [transient | persistent | sharedTransient];

The entity value can be a property expression, a local variable, or a formal parameter.

The syntax of the extended create instruction, which retrieves the object reference using an assignment instruction, is as follows.

reference := create class‑name(parameters) lifetime;

An assignment statement is required. You cannot use this syntax in a general assignment expression; for example, as a value passed to a parameter in a method call or the value in a return statement.

Description

You can optionally specify a class expression in the as clause of the create instruction but you cannot specify a class expression in the as clause of the extended create instruction. The class does not need to be an explicit class name; it can be a variable or any valid expression that yields a class. However, the class name must be explicit in the extended create instruction.

The as clause in the extended create instruction is not supported, because the class name must be specified so that the compiler can validate the signature of the create method call.

You cannot use the create instruction without parameters if the class of the object being created has a constructor that has parameters.

The extended create instruction syntax is allowed for any class, with or without an explicit constructor with or without parameters.

The transient, persistent, and sharedTransient modifiers specify whether the instance of the class being created is transient, shared transient, or persistent. If the modifier is omitted, the default lifetime for the class is used.

For details about:

Constructor create methods, see "Using Constructors and Destructors", in Chapter 4 of the JADE Development Environment User's Guide.
Shared transient transactions, see "beginTransientTransaction", earlier in this chapter. See also "Sharing Uncommitted Persistent Objects".
For details about the RootSchema classes for which you can create persistent instances, see "Instructions for Creating and Deleting Objects".

The create instruction on a Form subclass creates a GUI form. If you want to create a print form at run time that simulates the entire GUI process, use the GUIClass class createPrintForm method. (For details, see Chapter 1 of the JADE Encyclopaedia of Classes.)

create Instruction Examples

The following example shows the use of the create instruction without parameters.

createEmployee(newName, newAddress, newPhone: String;
               newBirthDate: Date): Employee;
vars
    newEmployee : Employee;
begin
    create newEmployee;
    newEmployee.name      := newName;
    newEmployee.address   := newAddress;
    newEmployee.phone     := newPhone;
    newEmployee.birthDate := newBirthDate;
    return newEmployee;
end;

The following example shows the use of the as clause in the create instruction.

createFault(faultType: Character): Fault;
vars
    fault : Fault;
begin
    if faultType = "N" then
        create fault as NewFeatureSuggestion;
    elseif faultType = "D" then
        create fault as DocumentationFault;
    else
        create fault as NormalFault;
    endif;
    ...                        // Do other initialization
    return fault;
end;

The following example shows the use of the create instruction without parameters when the class is not an explicit class name.

createFault(faultClass: Class): Fault;
vars
    fault : Fault;
begin
    create fault as faultClass;
    ...                        // Do other initialization
    return fault;
end;

Extended create Instruction Examples

The following example is an Employee class create method with parameters.

create(newName, newAddress, newPhone: String; newBirthDate: Date) updating;
begin
    name := newName;
    address := newAddress;
    phone := newPhone;
    birthDate := newBirthDate;
end;

The following is an example of an extended create instruction based on the above Employee class create method with parameters example.

createEmployee(newName, newAddress, newPhone: String; 
               newBirthDate: Date): Employee;
vars
    newEmployee : Employee;
begin
    newEmployee := create Employee(newName, newAddress, newPhone, newBirthDate);
    return newEmployee;
end;