afw_object.h

Go to the documentation of this file.

// See the 'COPYING' file in the project root for licensing information.
/*
 * Adaptive Framework interface helpers for afw_object* header
 *
 * Copyright (c) 2010-2023 Clemson University
 *
 */
 
#ifndef __AFW_OBJECT_H
#define __AFW_OBJECT_H
 
#include "afw_interface.h"
 
AFW_BEGIN_DECLARES
 
#define AFW_OBJECT_Q_CORE_ID_PREFIX AFW_Q__Adaptive
 
#define AFW_OBJECT_S_CORE_ID_PREFIX afw_s__Adaptive
 
#define AFW_OBJECT_Q_OBJECT_TYPE_ID_OBJECT AFW_Q__AdaptiveObject_
 
#define AFW_OBJECT_S_OBJECT_TYPE_ID_OBJECT afw_s__AdaptiveObject_
 
#define AFW_OBJECT_Q_OBJECT_TYPE_ID_OBJECT_TYPE AFW_Q__AdaptiveObjectType_
 
#define AFW_OBJECT_S_OBJECT_TYPE_ID_OBJECT_TYPE afw_s__AdaptiveObjectType_
 
#define AFW_OBJECT_Q_OBJECT_TYPE_ID_VALUE_META AFW_Q__AdaptiveValueMeta_
 
#define AFW_OBJECT_S_OBJECT_TYPE_ID_VALUE_META afw_s__AdaptiveValueMeta_
 
#define AFW_OBJECT_Q_OBJECT_TYPE_ID_DATA_TYPE AFW_Q__AdaptiveDataType_
 
#define AFW_OBJECT_S_OBJECT_TYPE_ID_DATA_TYPE afw_s__AdaptiveDataType_
 
#define AFW_OBJECT_Q_OBJECT_TYPE_ID_JOURNAL_ENTRY AFW_Q__AdaptiveJournalEntry_
 
#define AFW_OBJECT_S_OBJECT_TYPE_ID_JOURNAL_ENTRY afw_s__AdaptiveJournalEntry_
 
#define AFW_OBJECT_Q_OBJECT_TYPE_ID_PROVISIONING_PEER AFW_Q__AdaptiveProvisioningPeer_
 
#define AFW_OBJECT_S_OBJECT_TYPE_ID_PROVISIONING_PEER afw_s__AdaptiveProvisioningPeer_
 
#define AFW_OBJECT_Q_OBJECT_TYPE_ID_RESPONSE AFW_Q__AdaptiveResponse_
 
#define AFW_OBJECT_S_OBJECT_TYPE_ID_RESPONSE afw_s__AdaptiveResponse_
 
#define AFW_OBJECT_Q_PN_META AFW_Q__meta_
 
#define AFW_OBJECT_S_PN_META afw_s__meta_
 
#define AFW_OBJECT_Q_PN_OBJECT_ID AFW_Q_objectId
 
#define AFW_OBJECT_S_PN_OBJECT_ID afw_s_objectId
 
#define AFW_OBJECT_Q_PN_PATH AFW_Q_path
 
#define AFW_OBJECT_S_PN_PATH afw_s_path
 
#define AFW_OBJECT_Q_PN_ADAPTOR_ID AFW_Q_adaptorId
 
#define AFW_OBJECT_S_PN_ADAPTOR_ID afw_s_adaptorId
 
#define AFW_OBJECT_Q_PN_OBJECT_TYPE AFW_Q_objectType
 
#define AFW_OBJECT_S_PN_OBJECT_TYPE afw_s_objectType
 
#define AFW_OBJECT_Q_PN_PARENT_PATHS AFW_Q_parentPaths
 
#define AFW_OBJECT_S_PN_PARENT_PATHS afw_s_parentPaths
 
#define AFW_OBJECT_Q_PN_PROPERTY_TYPES AFW_Q_propertyTypes
 
#define AFW_OBJECT_S_PN_PROPERTY_TYPES afw_s_propertyTypes
 
#define AFW_OBJECT_Q_PN_META_OBJECTTYPE \
    AFW_OBJECT_Q_PN_META "." AFW_OBJECT_Q_PN_OBJECT_TYPE
 
#define AFW_OBJECT_S_PN_META_OBJECTTYPE afw_s_a_meta_objectType
 
#define AFW_OBJECT_ID_IS_OBJECT_TYPE(OBJECT_TYPE_ID) \
    afw_utf8_equal((OBJECT_TYPE_ID), &afw_s__AdaptiveObjectType_)
 
#define AFW_OBJECT_IS_CORE_OBJECT_TYPE_ID(OBJECT_TYPE_ID, OBJECT_ID) \
    AFW_OBJECT_ID_IS_OBJECT_TYPE(OBJECT_TYPE_ID) && \
    afw_utf8_starts_with((OBJECT_ID), &afw_s__Adaptive)
 
#define AFW_OBJECT_IS_CORE_TYPE_ID(ID) \
    afw_utf8_starts_with((ID), &afw_s__Adaptive)
 
 
AFW_DECLARE(afw_size_t)
afw_object_property_count(
    const afw_object_t *object,
    afw_xctx_t *xctx);
 
 
#define afw_object_is_immutable(instance, xctx) \
(afw_object_get_setter(instance, xctx) == NULL)
 
 
 
#define AFW_OBJECT_IMPL_ERROR_OBJECT_NOT_ENTITY \
AFW_THROW_ERROR_Z(general, "Object is not an entity", xctx)
 
 
#define AFW_OBJECT_ASSERT_ENTITY(instance, xctx) \
do { \
    if (instance->meta.embedding_object) \
        AFW_OBJECT_IMPL_ERROR_OBJECT_NOT_ENTITY; \
    } \
while (0)
 
 
#define AFW_OBJECT_ERROR_OBJECT_IMMUTABLE \
AFW_THROW_ERROR_Z(read_only, "Object immutable", xctx)
 
 
#define AFW_OBJECT_ASSERT_MUTABLE(instance, xctx) \
do { \
    if (afw_object_is_immutable(instance, xctx)) \
        AFW_OBJECT_ERROR_OBJECT_IMMUTABLE; \
    } \
while (0)
 
 
#define AFW_OBJECT_ERROR_PROPERTY_IMMUTABLE(property_name) \
AFW_THROW_ERROR_FZ(read_only, xctx, \
    "Object property %" AFW_UTF8_FMT " is immutable", \
    AFW_UTF8_FMT_ARG(property_name))
 
AFW_DECLARE(void)
afw_object_set_immutable(const afw_object_t *instance, afw_xctx_t *xctx);
 
 
AFW_DECLARE(void)
afw_object_remove_property(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    afw_xctx_t *xctx);
 
 
AFW_DECLARE(void)
afw_object_set_property(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    const afw_value_t *value,
    afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(void)
afw_object_set_property_as_date_from_parts(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    int year,
    int month,
    int day,
    int tz_hours_offset,
    int tz_minutes_offset,
    afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(void)
afw_object_set_property_as_dateTime_from_parts(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    int year,
    int month,
    int day,
    int hour,
    int minute,
    int second,
    int microsecond,
    int tz_hours_offset,
    int tz_minutes_offset,
    afw_xctx_t *xctx);
 
 
AFW_DECLARE(void)
afw_object_set_property_as_dayTimeDuration_from_parts(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    afw_boolean_t is_positive,
    int days,
    int hours,
    int minutes,
    int seconds,
    int microseconds,
    afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(void)
afw_object_set_property_as_time_from_parts(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    int hour,
    int minute,
    int second,
    int microsecond,
    int tz_hours_offset,
    int tz_minutes_offset,
    afw_xctx_t *xctx);
 
 
AFW_DECLARE(void)
afw_object_set_property_as_yearMonthDuration_from_parts(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    afw_boolean_t is_positive,
    int years,
    int months,
    afw_xctx_t *xctx);
 
 
AFW_DECLARE(void)
afw_object_set_property_as_string_from_utf8_z(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    const afw_utf8_z_t *string_z,
    afw_xctx_t *xctx);
 
 
#define AFW_OBJECT_GET_ENTITY(entity,object) \
    entity = object; \
    while (entity->meta.embedding_object) \
        entity = entity->meta.embedding_object
 
 
AFW_DEFINE_STATIC_INLINE(void)
afw_object_parse_entity_path_from_path(afw_utf8_t *entity_path,
    const afw_utf8_t *path)
{
    const afw_utf8_octet_t *s;
 
    entity_path->s = path->s;
    entity_path->len = path->len;
    for (s = path->s + path->len - 1;
        s > path->s && *s != '/';
        s--)
    {
        if (*s == '.') {
            entity_path->len = s - path->s;
        }
    }
}
 
 
AFW_DEFINE_STATIC_INLINE(const afw_object_t *)
afw_object_get_entity(const afw_object_t *object, afw_xctx_t *xctx)
{
    const afw_object_t *entity;
    AFW_OBJECT_GET_ENTITY(entity, object);
    return entity;
}
 
 
 
AFW_DEFINE_STATIC_INLINE(const afw_object_t *)
afw_object_resolve_instance(
    const afw_object_t *object,
    const afw_utf8_t *path,
    afw_xctx_t *xctx)
{
    if (object) return object;
    if (!path) return NULL;
    /* Will not happen if objects retrieved using afw_cache_* */
    AFW_THROW_ERROR_FZ(objects_needed, xctx, "%" AFW_UTF8_FMT,
        AFW_UTF8_FMT_ARG(path));
};
 
 
 
AFW_DECLARE(const afw_value_t *)
afw_object_get_property_compile_as(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    const afw_utf8_t *source_location,
    afw_compile_type_t compile_type,
    const afw_pool_t *p,
    afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(const afw_value_t *)
afw_object_get_property_compile_and_evaluate_as(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    const afw_utf8_t *source_location,
    afw_compile_type_t compile_type,
    const afw_pool_t *p,
    afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(const afw_value_t *)
afw_object_get_property_extended(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    afw_xctx_t *xctx);
 
 
AFW_DECLARE(const afw_value_t * const *)
afw_object_old_get_property_as_array_of_values(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    const afw_pool_t *p, afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(const afw_utf8_t * const *)
afw_object_old_get_property_as_array_of_strings(
    const afw_object_t *instance, const afw_utf8_t *property_name,
    const afw_pool_t *p, afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(const afw_value_t *)
afw_object_old_get_property_as_compiled_hybrid(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    const afw_utf8_t *source_location,
    const afw_compile_shared_t *shared,
    const afw_pool_t *p, afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(afw_boolean_t)
afw_object_old_get_property_as_boolean_deprecated(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    afw_xctx_t *xctx);
 
 
AFW_DECLARE(afw_integer_t)
afw_object_old_get_property_as_integer_deprecated(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    afw_boolean_t *found,
    afw_xctx_t *xctx);
 
 
AFW_DECLARE(const afw_utf8_t *)
afw_object_old_get_property_as_utf8(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    const afw_pool_t *p,
    afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(const afw_utf8_z_t *)
afw_object_old_get_property_as_utf8_z(
    const afw_object_t *instance,
    const afw_utf8_t *property_name,
    const afw_pool_t *p,
    afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(void)
afw_object_merge(
    const afw_object_t *instance,
    const afw_object_t *from,
    afw_boolean_t replace,
    afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(const afw_object_associative_array_t *)
afw_object_memory_associative_array_create(
    const afw_pool_t *p, afw_xctx_t *xctx);
 
 
#define AFW_OBJECT_MEMORY_OPTION_default              0
 
 
#define AFW_OBJECT_MEMORY_OPTION_unmanaged            (1 << 0)
 
 
#define AFW_OBJECT_MEMORY_OPTION_cede_p               (1 << 1)
 
 
#define AFW_OBJECT_MEMORY_OPTION_clone_on_set            (1 << 2)
 
 
#define AFW_OBJECT_MEMORY_OPTION_cede_p_and_clone_on_set \
    AFW_OBJECT_MEMORY_OPTION_cede_p + \
    AFW_OBJECT_MEMORY_OPTION_clone_on_set
 
 
#define AFW_OBJECT_MEMORY_OPTION_IS(options_mask, option) \
    ((((options_mask) & (AFW_OBJECT_MEMORY_OPTION_ ## option))) != 0)
 
 
AFW_DECLARE(const afw_object_t *)
afw_object_create_with_options(
    int options, const afw_pool_t * p, afw_xctx_t *xctx);
 
 
AFW_DECLARE(const afw_object_t *)
afw_object_create_composite(
    afw_boolean_t mutable,
    const afw_pool_t *p, afw_xctx_t *xctx,
    ...);
 
 
 
typedef const afw_value_t *(*afw_object_properties_callback_entry_get_t) (
    void *data,
    const afw_utf8_t *property_name,
    afw_xctx_t *xctx);
 
 
 
typedef void (*afw_object_properties_callback_entry_set_t) (
    void *data,
    const afw_utf8_t *property_name,
    const afw_value_t *value,
    afw_xctx_t *xctx);
 
 
 
struct afw_object_properties_callback_entry_s {
    const afw_utf8_t *property_name;
    afw_object_properties_callback_entry_get_t get;
    afw_object_properties_callback_entry_set_t set;
};
 
 
 
AFW_DECLARE(const afw_object_t *)
afw_object_create_properties_callback(
    void *data,
    afw_size_t count,
    const afw_object_properties_callback_entry_t callbacks[],
    const afw_pool_t *p, afw_xctx_t *xctx);
 
 
 
#define afw_object_create_and_cede_p(p, xctx) \
    afw_object_create_with_options( \
        AFW_OBJECT_MEMORY_OPTION_cede_p, p, xctx)
 
 
#define afw_object_create_managed(p, xctx) \
    afw_object_create_with_options( \
        AFW_OBJECT_MEMORY_OPTION_default, p, xctx)
 
 
#define afw_object_create_clone_on_set(p, xctx) \
    afw_object_create_with_options( \
        AFW_OBJECT_MEMORY_OPTION_clone_on_set, p, xctx)
 
 
#define afw_object_create(p, xctx) \
    afw_object_create_with_options( \
        AFW_OBJECT_MEMORY_OPTION_unmanaged, p, xctx)
 
 
AFW_DECLARE(const afw_object_t *)
afw_object_create_embedded(
    const afw_object_t *embedding_object,
    const afw_utf8_t *property_name,
    afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(const afw_object_t *)
afw_object_insure_embedded_exists(
    const afw_object_t *embedding_object,
    const afw_utf8_t *property_name,
    afw_xctx_t *xctx);
 
 
 
 
#define AFW_OBJECT_CREATE_ENTITY_OR_EMBEDDED( \
    result,embedding_object,property_name,always_create_unmanaged, \
    cede_p,entity_p,xctx) \
    if (always_create_unmanaged || \
        (property_name && afw_utf8_equal(property_name, &afw_s__meta_))) \
    { \
        result = afw_object_create(entity_p, xctx); \
    } \
    else if (embedding_object) { \
        result = afw_object_create_embedded( \
            embedding_object, property_name, xctx); \
    } \
    else { \
        result = afw_object_create_with_options( \
            (cede_p) \
            ? AFW_OBJECT_MEMORY_OPTION_cede_p \
            : AFW_OBJECT_MEMORY_OPTION_default, \
            entity_p, xctx); \
    } \
 
 
 
AFW_DECLARE(const afw_object_t *)
afw_object_create_clone(
    const afw_object_t *object,
    const afw_pool_t *p,
    afw_xctx_t *xctx);
 
 
 
 
#define afw_object_create_clone_to_managed_object( \
    object, p, xctx) \
    afw_data_type_object_create_clone_to_managed_object( \
        object, p, xctx)
 
 
 
AFW_DECLARE(const afw_object_t *)
afw_object_create_merged(
    const afw_object_t *primary,
    const afw_object_t *secondary,
    const afw_pool_t *p,
    afw_xctx_t *xctx);
 
 
 
 
AFW_DECLARE(const afw_object_t *)
afw_object_aggregate_external_create(
    const afw_object_t * const *object_list,
    const afw_pool_t *p,
    afw_xctx_t *xctx);
 
 
 
AFW_DECLARE(const afw_object_t *)
afw_object_create_const_from_key_value_strings_z(
    const afw_utf8_t *path,
    const afw_utf8_z_t * const *pairs,
    const afw_pool_t *p,
    afw_xctx_t *xctx);
 
AFW_END_DECLARES
 
#endif /* __AFW_OBJECT_H */