Skip to main content
The result types provide a type-safe wrapper for HL7 operation results, distinguishing between successful operations, partial successes, functional rejections, and technical errors.

​
Hl7Result<T>

Generic result wrapper that encapsulates the outcome of an HL7 operation. Package: com.hl7client.model.result

​
Type Parameters

​
T
Type
The type of data contained in the result (typically a response DTO)

​
Fields

​
status
Hl7Status
required
The operation status (OK, PARTIAL, REJECTED, or ERROR)
​
data
T
The response data (present for OK, PARTIAL, and REJECTED statuses)
​
issue
Hl7Error
Error information (present for REJECTED and ERROR statuses)
​
details
List<Hl7ItemError>
List of item-level errors (present for PARTIAL status)

​
Factory Methods

​
ok()

Creates a successful result with data and no errors. 
public static <T> Hl7Result<T> ok(T data)
​
data
T
required
The successful response data
Returns: Hl7Result<T> with status OK Example: 
ElegibilidadResponse response = // ... parse response
return Hl7Result.ok(response);

​
partial()

Creates a partially successful result with data and item-level warnings/errors. 
public static <T> Hl7Result<T> partial(
    T data,
    List<Hl7ItemError> details
)
​
data
T
required
The response data (cannot be null)
​
details
List<Hl7ItemError>
required
List of item-level errors or warnings
Returns: Hl7Result<T> with status PARTIAL Example: 
List<Hl7ItemError> errors = new ArrayList<>();
for (RegistracionDetalle item : response.getDetalle()) {
    if (item.getRecha() != 0) {
        errors.add(new Hl7ItemError(
            String.valueOf(item.getRecha()),
            item.getDenoItem(),
            Hl7ItemErrorOrigin.DETALLE
        ));
    }
}

if (!errors.isEmpty()) {
    return Hl7Result.partial(response, errors);
}

​
rejected()

Creates a functionally rejected result (business rules violation). 
public static <T> Hl7Result<T> rejected(
    T data,
    Hl7Error functionalError
)
​
data
T
required
The response data containing rejection information
​
functionalError
Hl7Error
required
The functional rejection error
Returns: Hl7Result<T> with status REJECTED Example: 
if (cabecera.getRechaCabecera() != 0) {
    Hl7Error error = Hl7Error.functional(
        String.valueOf(cabecera.getRechaCabecera()),
        cabecera.getRechaCabeDeno()
    );
    return Hl7Result.rejected(response, error);
}

​
error()

Creates a technical error result (infrastructure/communication failure). 
public static <T> Hl7Result<T> error(Hl7Error technicalError)
​
technicalError
Hl7Error
required
The technical error details
Returns: Hl7Result<T> with status ERROR and no data Example: 
try {
    // ... make API call
} catch (IOException e) {
    return Hl7Result.error(
        Hl7Error.technical(
            "Network error: " + e.getMessage(),
            Hl7ErrorOrigin.TRANSPORTE
        )
    );
}

​
Helper Methods

​
isOk()
boolean
Returns true if status is OK
​
isPartial()
boolean
Returns true if status is PARTIAL
​
isRejected()
boolean
Returns true if status is REJECTED
​
isError()
boolean
Returns true if status is ERROR

​
Accessor Methods

​
getStatus()
Hl7Status
Returns the operation status
​
getData()
Optional<T>
Returns the data wrapped in an Optional
​
getIssue()
Optional<Hl7Error>
Returns the error wrapped in an Optional
​
getDetails()
List<Hl7ItemError>
Returns an immutable list of item-level errors

​
Usage Example

Hl7Result<ElegibilidadResponse> result = hl7Service.checkElegibilidad(request);

if (result.isOk()) {
    ElegibilidadResponse response = result.getData().get();
    // Process successful response
    displayPatientInfo(response);
    
} else if (result.isPartial()) {
    ElegibilidadResponse response = result.getData().get();
    // Process response with warnings
    displayPatientInfo(response);
    
    for (Hl7ItemError detail : result.getDetails()) {
        logger.warn("Item warning: {}", detail.getMessage());
    }
    
} else if (result.isRejected()) {
    // Handle business rule rejection
    Hl7Error error = result.getIssue().get();
    showError("Request rejected: " + error.getMessage());
    
    if (error.isSession()) {
        // Prompt for re-login
        redirectToLogin();
    }
    
} else if (result.isError()) {
    // Handle technical error
    Hl7Error error = result.getIssue().get();
    logger.error("Technical error: {}", error.getMessage());
    showError("System error. Please try again.");
}

​
Hl7Status

Enumeration of possible operation statuses. Package: com.hl7client.model.result
​
OK
Hl7Status
Operation completed successfully with no issues
​
PARTIAL
Hl7Status
Operation completed with some items having warnings or errors
​
REJECTED
Hl7Status
Operation rejected due to business rules violation
​
ERROR
Hl7Status
Operation failed due to technical error (network, session, parsing, etc.)

​
Status Flow Diagram

​
Hl7Error

Represents an error at the operation level (header/cabecera). Package: com.hl7client.model.result

​
Fields

​
code
String
Error code (may be null for technical errors)
​
message
String
required
Human-readable error message
​
origin
Hl7ErrorOrigin
required
The origin/layer where the error occurred
​
session
boolean
Whether this is a session expiration error

​
Factory Methods

​
functional()

Creates a functional/business rule error. 
public static Hl7Error functional(String code, String message)
​
code
String
required
Error code from the HL7 provider
​
message
String
required
Error message from the HL7 provider
Returns: Hl7Error with origin CABECERA Example: 
Hl7Error error = Hl7Error.functional(
    "2001",
    "Credencial no encontrada"
);

​
technical()

Creates a technical/infrastructure error. 
public static Hl7Error technical(String message, Hl7ErrorOrigin origin)
​
message
String
required
Error description
​
origin
Hl7ErrorOrigin
required
The layer where the error occurred
Returns: Hl7Error with no code Example: 
Hl7Error error = Hl7Error.technical(
    "Connection timeout",
    Hl7ErrorOrigin.TRANSPORTE
);

​
sessionExpired()

Creates a session expiration error. 
public static Hl7Error sessionExpired()
Returns: Hl7Error with predefined session error details Example: 
if (response.getStatusCode() == 401) {
    return Hl7Result.error(Hl7Error.sessionExpired());
}

​
Methods

​
isSession()
boolean
Returns true if this is a session expiration error
​
getCode()
String
Returns the error code (may be null)
​
getMessage()
String
Returns the error message
​
getOrigin()
Hl7ErrorOrigin
Returns the error origin

​
Hl7ErrorOrigin

Enumeration of error origin layers. Package: com.hl7client.model.result
​
CABECERA
Hl7ErrorOrigin
Error in the response header/cabecera (functional rejection)
​
DETALLE
Hl7ErrorOrigin
Error in response detail items
​
TRANSPORTE
Hl7ErrorOrigin
Network or HTTP transport error
​
PARSEO
Hl7ErrorOrigin
JSON parsing or deserialization error

​
Error Origin Examples

​
Hl7ItemError

Represents an error at the item/detail level. Package: com.hl7client.model.result

​
Constructor

public Hl7ItemError(
    String code,
    String message,
    Hl7ItemErrorOrigin origin
)
​
code
String
required
Error code
​
message
String
required
Error message
​
origin
Hl7ItemErrorOrigin
required
The detail level where the error occurred

​
Methods

​
getCode()
String
Returns the error code
​
getMessage()
String
Returns the error message
​
getOrigin()
Hl7ItemErrorOrigin
Returns the error origin

​
Example

List<Hl7ItemError> errors = new ArrayList<>();

for (RegistracionDetalle item : response.getDetalle()) {
    if (item.getRecha() != 0) {
        errors.add(new Hl7ItemError(
            String.valueOf(item.getRecha()),
            item.getDenoItem(),
            Hl7ItemErrorOrigin.DETALLE
        ));
    }
}

if (!errors.isEmpty()) {
    return Hl7Result.partial(response, errors);
}

​
Hl7ItemErrorOrigin

Enumeration of item-level error origins. Package: com.hl7client.model.result
​
DETALLE
Hl7ItemErrorOrigin
Error in a detail item (main item level)
​
SUBDETALLE
Hl7ItemErrorOrigin
Error in a sub-detail item (nested items like practices, supplies, etc.)
Currently, only DETALLE is actively used in the client implementation.

​
Complete Example

Here’s a complete example showing how to use all result types together: 
public Hl7Result<RegistracionResponse> registrarServicios(
    RegistracionRequest request
) {
    try {
        // Make API call
        HttpResponse<String> httpResponse = httpClient.send(
            buildRequest(request),
            HttpResponse.BodyHandlers.ofString()
        );
        
        // Check session
        if (httpResponse.statusCode() == 401) {
            return Hl7Result.error(Hl7Error.sessionExpired());
        }
        
        // Check transport errors
        if (httpResponse.statusCode() >= 500) {
            return Hl7Result.error(
                Hl7Error.technical(
                    "Server error: " + httpResponse.statusCode(),
                    Hl7ErrorOrigin.TRANSPORTE
                )
            );
        }
        
        // Parse response
        RegistracionResponse response;
        try {
            response = objectMapper.readValue(
                httpResponse.body(),
                RegistracionResponse.class
            );
        } catch (JsonProcessingException e) {
            return Hl7Result.error(
                Hl7Error.technical(
                    "Parse error: " + e.getMessage(),
                    Hl7ErrorOrigin.PARSEO
                )
            );
        }
        
        // Check cabecera rejection
        RegistracionCabecera cabecera = response.getCabecera();
        if (cabecera.getRechaCabecera() != 0) {
            return Hl7Result.rejected(
                response,
                Hl7Error.functional(
                    String.valueOf(cabecera.getRechaCabecera()),
                    cabecera.getRechaCabeDeno()
                )
            );
        }
        
        // Check for partial success (item-level errors)
        if (response.getDetalle() != null) {
            List<Hl7ItemError> errors = new ArrayList<>();
            
            for (RegistracionDetalle item : response.getDetalle()) {
                if (item.getRecha() != 0) {
                    errors.add(new Hl7ItemError(
                        String.valueOf(item.getRecha()),
                        item.getDenoItem(),
                        Hl7ItemErrorOrigin.DETALLE
                    ));
                }
            }
            
            if (!errors.isEmpty()) {
                return Hl7Result.partial(response, errors);
            }
        }
        
        // Complete success
        return Hl7Result.ok(response);
        
    } catch (IOException e) {
        return Hl7Result.error(
            Hl7Error.technical(
                "Network error: " + e.getMessage(),
                Hl7ErrorOrigin.TRANSPORTE
            )
        );
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        return Hl7Result.error(
            Hl7Error.technical(
                "Request interrupted",
                Hl7ErrorOrigin.TRANSPORTE
            )
        );
    }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us