gcloud/lib/src/db/model_db_impl.dart - third_party/dart-pkg - Git at Google

 // Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.

 part of '../../db.dart';

 /// An implementation of [ModelDB] based on model class annotations.
 ///
 /// The two constructors will scan loaded dart libraries for classes with a
 /// [Kind] annotation.
 ///
 /// An example on how to write a model class is:
 ///     @Kind
 ///     class Person extends db.Model {
 ///       @StringProperty
 ///       String name;
 ///
 ///       @IntProperty
 ///       int age;
 ///
 ///       @DateTimeProperty
 ///       DateTime dateOfBirth;
 ///     }
 ///
 /// These classes must either extend [Model] or [ExpandoModel]. Furthermore
 /// they must have an empty default constructor which can be used to construct
 /// model objects when doing lookups/queries from datastore.
 class ModelDBImpl implements ModelDB {
   final Map<_ModelDescription, Map<String, Property>> _modelDesc2Properties =
       {};
   final Map<String, _ModelDescription> _kind2ModelDesc = {};
   final Map<_ModelDescription, mirrors.ClassMirror> _modelDesc2ClassMirror = {};
   final Map<_ModelDescription, Type> _type2ModelDesc = {};
   final Map<Type, _ModelDescription> _modelDesc2Type = {};

   /// Initializes a new [ModelDB] from all libraries.
   ///
   /// This will scan all libraries for classes with a [Kind] annotation.
   ///
   /// In case an error is encountered (e.g. two model classes with the same kind
   /// name) a [StateError] will be thrown.
   ModelDBImpl() {
     // WARNING: This is O(n) of the source code, which is very bad!
     // Would be nice to have: `currentMirrorSystem().subclassesOf(Model)`
     _initialize(mirrors.currentMirrorSystem().libraries.values);
   }

   /// Initializes a new [ModelDB] from all libraries.
   ///
   /// This will scan the given [librarySymbol] for classes with a [Kind]
   /// annotation.
   ///
   /// In case an error is encountered (e.g. two model classes with the same kind
   /// name) a [StateError] will be thrown.
   ModelDBImpl.fromLibrary(Symbol librarySymbol) {
     _initialize([mirrors.currentMirrorSystem().findLibrary(librarySymbol)]);
   }

   /// Converts a [ds.Key] to a [Key]. The key returned will have the correct
   /// id type which is either `Key<String>` or `Key<int>`.
   @override
   Key fromDatastoreKey(ds.Key datastoreKey) {
     var namespace = Partition(datastoreKey.partition.namespace);
     var key = namespace.emptyKey;
     for (var element in datastoreKey.elements) {
       var type = _type2ModelDesc[_kind2ModelDesc[element.kind]!];
       if (type == null) {
         throw StateError(
             'Could not find a model associated with kind "${element.kind}". '
             'Please ensure a model class was annotated with '
             '`@Kind(name: "${element.kind}")`.');
       }
       final elementId = element.id;
       if (elementId is String) {
         key = key.append<String>(type, id: elementId);
       } else if (elementId is int) {
         key = key.append<int>(type, id: elementId);
       } else {
         throw StateError('Key must be either String or int, but '
             'was ${elementId.runtimeType} for key ${element.kind}');
       }
     }
     return key;
   }

   /// Converts a [Key] to a [ds.Key].
   @override
   ds.Key toDatastoreKey(Key dbKey) {
     var elements = <ds.KeyElement>[];
     var currentKey = dbKey;
     while (!currentKey.isEmpty) {
       var id = currentKey.id;

       var modelDescription = _modelDescriptionForType(currentKey.type)!;
       var kind = modelDescription.kindName(this);

       var useIntegerId = modelDescription.useIntegerId;

       if (useIntegerId && id != null && id is! int) {
         throw ArgumentError('Expected an integer id property but '
             'id was of type ${id.runtimeType}');
       }
       if (!useIntegerId && (id != null && id is! String)) {
         throw ArgumentError('Expected a string id property but '
             'id was of type ${id.runtimeType}');
       }

       elements.add(ds.KeyElement(kind, id));
       currentKey = currentKey.parent!;
     }
     var partition = currentKey._parent as Partition;
     return ds.Key(elements.reversed.toList(),
         partition: ds.Partition(partition.namespace));
   }

   /// Converts a [Model] instance to a [ds.Entity].
   @override
   ds.Entity toDatastoreEntity(Model model) {
     try {
       var modelDescription = _modelDescriptionForType(model.runtimeType)!;
       return modelDescription.encodeModel(this, model);
     } catch (error, stack) {
       throw ArgumentError('Error while encoding entity ($error, $stack).');
     }
   }

   /// Converts a [ds.Entity] to a [Model] instance.
   @override
   T? fromDatastoreEntity<T extends Model>(ds.Entity? entity) {
     if (entity == null) {
       return null;
     }
     var key = fromDatastoreKey(entity.key);
     var kind = entity.key.elements.last.kind;
     var modelDescription = _kind2ModelDesc[kind];
     if (modelDescription == null) {
       throw StateError('Trying to deserialize entity of kind '
           '$kind, but no Model class available for it.');
     }

     try {
       return modelDescription.decodeEntity<T>(this, key, entity);
     } catch (error, stack) {
       throw StateError('Error while decoding entity ($error, $stack).');
     }
   }

   /// Returns the string representation of the kind of model class [type].
   ///
   /// If the model class `type` is not found it will throw an `ArgumentError`.
   @override
   String kindName(Type type) {
     var kind = _modelDesc2Type[type]?.kind;
     if (kind == null) {
       throw ArgumentError('The class $type was not associated with a kind.');
     }
     return kind;
   }

   /// Returns the name of the property corresponding to the kind [kind] and
   /// [fieldName].
   @override
   String? fieldNameToPropertyName(String kind, String fieldName) {
     var modelDescription = _kind2ModelDesc[kind];
     if (modelDescription == null) {
       throw ArgumentError('The kind "$kind" is unknown.');
     }
     return modelDescription.fieldNameToPropertyName(fieldName);
   }

   /// Converts [value] according to the [Property] named [name] in [type].
   @override
   Object? toDatastoreValue(String kind, String fieldName, Object? value,
       {bool forComparison = false}) {
     var modelDescription = _kind2ModelDesc[kind];
     if (modelDescription == null) {
       throw ArgumentError('The kind "$kind" is unknown.');
     }
     return modelDescription.encodeField(this, fieldName, value,
         forComparison: forComparison);
   }

   Iterable<_ModelDescription> get _modelDescriptions {
     return _modelDesc2Type.values;
   }

   Map<String, Property> _propertiesForModel(
       _ModelDescription modelDescription) {
     return _modelDesc2Properties[modelDescription]!;
   }

   _ModelDescription? _modelDescriptionForType(Type? type) {
     return _modelDesc2Type[type!];
   }

   mirrors.ClassMirror? _modelClass(_ModelDescription md) {
     return _modelDesc2ClassMirror[md];
   }

   void _initialize(Iterable<mirrors.LibraryMirror> libraries) {
     for (var lm in libraries) {
       lm.declarations.values
           .whereType<mirrors.ClassMirror>()
           .where((d) => d.hasReflectedType)
           .forEach(_tryLoadNewModelClass);
     }

     // Ask every [ModelDescription] to compute whatever global state it wants
     // to have.
     for (var modelDescription in _modelDescriptions) {
       modelDescription.initialize(this);
     }

     // Ask every [ModelDescription] whether we should register it with a given
     // kind name.
     for (var modelDescription in _modelDescriptions) {
       var kindName = modelDescription.kindName(this);
       if (_kind2ModelDesc.containsKey(kindName)) {
         throw StateError('Cannot have two ModelDescriptions '
             'with the same kind ($kindName)');
       }
       _kind2ModelDesc[kindName] = modelDescription;
     }
   }

   void _tryLoadNewModelClass(mirrors.ClassMirror classMirror) {
     Kind? kindAnnotation;
     for (var instance in classMirror.metadata) {
       if ((instance.reflectee as Object).runtimeType == Kind) {
         if (kindAnnotation != null) {
           throw StateError(
               'Cannot have more than one ModelMetadata() annotation '
               'on a Model class');
         }
         kindAnnotation = instance.reflectee as Kind?;
       }
     }

     if (kindAnnotation != null) {
       var name = kindAnnotation.name;
       var integerId = kindAnnotation.idType == IdType.Integer;
       var stringId = kindAnnotation.idType == IdType.String;

       // Fall back to the class name.
       name ??= mirrors.MirrorSystem.getName(classMirror.simpleName);

       // This constraint should be guaranteed by the Kind() const constructor.
       assert((integerId && !stringId) || (!integerId && stringId));

       _tryLoadNewModelClassFull(classMirror, name, integerId);
     }
   }

   static bool _isRequiredAnnotation(mirrors.InstanceMirror annotation) {
     return annotation.type.simpleName == #Required;
   }

   /// Returns true if a  constructor invocation is valid even if the specified
   /// [parameter] is omitted.
   ///
   /// This is  true for named parameters, optional parameters, and parameters
   /// with a default value.
   static bool _canBeOmitted(mirrors.ParameterMirror parameter) {
     if (parameter.metadata.any(_isRequiredAnnotation)) {
       return false;
     }
     return parameter.isOptional ||
         parameter.isNamed ||
         parameter.hasDefaultValue;
   }

   /// Returns true if the specified [classMirror] has a default (unnamed)
   /// constructor that accepts an empty arguments list.
   @visibleForTesting
   static bool hasDefaultConstructor(mirrors.ClassMirror classMirror) {
     for (var declaration in classMirror.declarations.values) {
       if (declaration is mirrors.MethodMirror) {
         if (declaration.isConstructor &&
             declaration.constructorName == const Symbol('') &&
             declaration.parameters.every(_canBeOmitted)) {
           return true;
         }
       }
     }
     return false;
   }

   void _tryLoadNewModelClassFull(
       mirrors.ClassMirror modelClass, String name, bool useIntegerId) {
     assert(!_modelDesc2Type.containsKey(modelClass.reflectedType));

     _ModelDescription modelDesc;
     if (_isExpandoClass(modelClass)) {
       modelDesc = _ExpandoModelDescription(name, useIntegerId);
     } else {
       modelDesc = _ModelDescription(name, useIntegerId);
     }

     _type2ModelDesc[modelDesc] = modelClass.reflectedType;
     _modelDesc2Type[modelClass.reflectedType] = modelDesc;
     _modelDesc2ClassMirror[modelDesc] = modelClass;
     _modelDesc2Properties[modelDesc] =
         _propertiesFromModelDescription(modelClass);

     // Ensure we have an empty constructor.
     if (!hasDefaultConstructor(modelClass)) {
       throw StateError('Class ${modelClass.simpleName} does not have a default '
           'constructor.');
     }
   }

   Map<String, Property> _propertiesFromModelDescription(
       mirrors.ClassMirror modelClassMirror) {
     var properties = <String, Property>{};
     var propertyNames = <String>{};

     // Loop over all classes in the inheritance path up to the Object class.
     while (modelClassMirror.superclass != null) {
       var memberMap = modelClassMirror.instanceMembers;
       // Loop over all declarations (which includes fields)
       modelClassMirror.declarations
           .forEach((Symbol fieldSymbol, mirrors.DeclarationMirror decl) {
         // Look if the symbol is a getter and we have metadata attached to it.
         if (memberMap.containsKey(fieldSymbol) &&
             memberMap[fieldSymbol]!.isGetter) {
           final propertyAnnotations = decl.metadata
               .map((mirrors.InstanceMirror mirror) => mirror.reflectee)
               .whereType<Property>()
               .toList();

           if (propertyAnnotations.length > 1) {
             throw StateError(
                 'Cannot have more than one Property annotation on a model '
                 'field.');
           } else if (propertyAnnotations.length == 1) {
             var property = propertyAnnotations.first;

             // Get a String representation of the field and the value.
             var fieldName = mirrors.MirrorSystem.getName(fieldSymbol);

             // Determine the name to use for the property in datastore.
             var propertyName = property.propertyName;
             propertyName ??= fieldName;

             if (properties.containsKey(fieldName)) {
               throw StateError(
                   'Cannot have two Property objects describing the same field '
                   'in a model object class hierarchy.');
             }

             if (propertyNames.contains(propertyName)) {
               throw StateError(
                   'Cannot have two Property objects mapping to the same '
                   'datastore property name "$propertyName".');
             }
             properties[fieldName] = property;
             propertyNames.add(propertyName);
           }
         }
       });
       modelClassMirror = modelClassMirror.superclass!;
     }

     return properties;
   }

   final _originalExpandoModelClass = mirrors.reflectClass(ExpandoModel);
   final _originalModelClass = mirrors.reflectClass(Model);

   bool _isExpandoClass(mirrors.ClassMirror? modelClass) {
     while (modelClass != null && modelClass.superclass != modelClass) {
       if (modelClass.originalDeclaration == _originalExpandoModelClass) {
         return true;
       } else if (modelClass.originalDeclaration == _originalModelClass) {
         return false;
       }

       modelClass = modelClass.superclass;
     }
     throw StateError('This should be unreachable.');
   }
 }

 class _ModelDescription<T extends Model> {
   final HashMap<String, String> _property2FieldName = HashMap<String, String>();
   final HashMap<String, String> _field2PropertyName = HashMap<String, String>();
   final Set<String> _indexedProperties = <String>{};
   final Set<String> _unIndexedProperties = <String>{};

   final String kind;
   final bool useIntegerId;

   _ModelDescription(this.kind, this.useIntegerId);

   void initialize(ModelDBImpl db) {
     // Compute propertyName -> fieldName mapping.
     db._propertiesForModel(this).forEach((String fieldName, Property prop) {
       // The default of a datastore property name is the fieldName.
       // It can be overridden with [Property.propertyName].
       var propertyName = prop.propertyName;
       propertyName ??= fieldName;

       _property2FieldName[propertyName] = fieldName;
       _field2PropertyName[fieldName] = propertyName;
     });

     // Compute properties & unindexed properties
     db._propertiesForModel(this).forEach((String fieldName, Property prop) {
       var propertyName = prop.propertyName;
       propertyName ??= fieldName;

       if (prop.indexed) {
         _indexedProperties.add(propertyName);
       } else {
         _unIndexedProperties.add(propertyName);
       }
     });
   }

   String kindName(ModelDBImpl db) => kind;

   ds.Entity encodeModel(ModelDBImpl db, T model) {
     var key = db.toDatastoreKey(model.key);

     var properties = <String, Object?>{};
     var mirror = mirrors.reflect(model);

     db._propertiesForModel(this).forEach((String fieldName, Property prop) {
       _encodeProperty(db, model, mirror, properties, fieldName, prop);
     });

     return ds.Entity(key, properties,
         unIndexedProperties: _unIndexedProperties);
   }

   void _encodeProperty(
       ModelDBImpl db,
       Model model,
       mirrors.InstanceMirror mirror,
       Map properties,
       String fieldName,
       Property prop) {
     var propertyName = prop.propertyName;
     propertyName ??= fieldName;

     var value =
         mirror.getField(mirrors.MirrorSystem.getSymbol(fieldName)).reflectee;
     if (!prop.validate(db, value)) {
       throw StateError('Property validation failed for '
           'property $fieldName while trying to serialize entity of kind '
           '${model.runtimeType}. ');
     }
     properties[propertyName] = prop.encodeValue(db, value);
   }

   H decodeEntity<H extends Model>(ModelDBImpl db, Key key, ds.Entity entity) {
     // NOTE: this assumes a default constructor for the model classes!
     var classMirror = db._modelClass(this)!;
     var mirror = classMirror.newInstance(const Symbol(''), []);

     // Set the id and the parent key
     final model = mirror.reflectee as Model;
     model.id = key.id;
     model.parentKey = key.parent;

     db._propertiesForModel(this).forEach((String fieldName, Property prop) {
       _decodeProperty(db, entity, mirror, fieldName, prop);
     });
     return mirror.reflectee as H;
   }

   void _decodeProperty(ModelDBImpl db, ds.Entity entity,
       mirrors.InstanceMirror mirror, String fieldName, Property prop) {
     var propertyName = fieldNameToPropertyName(fieldName);

     var rawValue = entity.properties[propertyName!];
     var value = prop.decodePrimitiveValue(db, rawValue);

     if (!prop.validate(db, value)) {
       throw StateError('Property validation failed while '
           'trying to deserialize entity of kind '
           '${entity.key.elements.last.kind} (property name: $propertyName)');
     }

     try {
       mirror.setField(mirrors.MirrorSystem.getSymbol(fieldName), value);
       // ignore: avoid_catching_errors
     } on TypeError catch (error) {
       throw StateError(
         'Error trying to set property "${prop.propertyName}" '
         'to $value for field "$fieldName": $error',
       );
     }
   }

   String? fieldNameToPropertyName(String fieldName) {
     return _field2PropertyName[fieldName];
   }

   String? propertyNameToFieldName(ModelDBImpl db, String propertySearchName) {
     return _property2FieldName[propertySearchName];
   }

   Object? encodeField(ModelDBImpl db, String fieldName, Object? value,
       {bool enforceFieldExists = true, bool forComparison = false}) {
     var property = db._propertiesForModel(this)[fieldName];
     if (property != null) {
       return property.encodeValue(db, value, forComparison: forComparison);
     }
     if (enforceFieldExists) {
       throw ArgumentError(
           'A field named "$fieldName" does not exist in kind "$kind".');
     }
     return null;
   }
 }

 // NOTE/TODO:
 // Currently expanded properties are only
 //   * decoded if there are no clashes in [usedNames]
 //   * encoded if there are no clashes in [usedNames]
 // We might want to throw an error if there are clashes, because otherwise
 //   - we may end up removing properties after a read-write cycle
 //   - we may end up dropping added properties in a write
 // ([usedNames] := [realFieldNames] + [realPropertyNames])
 class _ExpandoModelDescription extends _ModelDescription<ExpandoModel> {
   late Set<String> realFieldNames;
   late Set<String> realPropertyNames;
   late Set<String> usedNames;

   _ExpandoModelDescription(String kind, bool useIntegerId)
       : super(kind, useIntegerId);

   @override
   void initialize(ModelDBImpl db) {
     super.initialize(db);

     realFieldNames = Set<String>.from(_field2PropertyName.keys);
     realPropertyNames = Set<String>.from(_property2FieldName.keys);
     usedNames = <String>{}
       ..addAll(realFieldNames)
       ..addAll(realPropertyNames);
   }

   @override
   ds.Entity encodeModel(ModelDBImpl db, ExpandoModel model) {
     var entity = super.encodeModel(db, model);
     var properties = entity.properties;
     model.additionalProperties.forEach((String key, Object? value) {
       // NOTE: All expanded properties will be indexed.
       if (!usedNames.contains(key)) {
         properties[key] = value;
       }
     });
     return entity;
   }

   @override
   T decodeEntity<T extends Model>(ModelDBImpl db, Key key, ds.Entity entity) {
     var model = super.decodeEntity(db, key, entity) as ExpandoModel;
     var properties = entity.properties;
     properties.forEach((String key, Object? value) {
       if (!usedNames.contains(key)) {
         model.additionalProperties[key] = value;
       }
     });
     // TODO: check if there is a more elegant solution than this
     return model as T;
   }

   @override
   String fieldNameToPropertyName(String fieldName) {
     var propertyName = super.fieldNameToPropertyName(fieldName);
     // If the ModelDescription doesn't know about [fieldName], it's an
     // expanded property, where propertyName == fieldName.
     propertyName ??= fieldName;
     return propertyName;
   }

   @override
   String propertyNameToFieldName(ModelDBImpl db, String propertyName) {
     var fieldName = super.propertyNameToFieldName(db, propertyName);
     // If the ModelDescription doesn't know about [propertyName], it's an
     // expanded property, where propertyName == fieldName.
     fieldName ??= propertyName;
     return fieldName;
   }

   @override
   Object encodeField(ModelDBImpl db, String fieldName, Object? value,
       {bool enforceFieldExists = true, bool forComparison = false}) {
     // The [enforceFieldExists] argument is intentionally ignored.

     var primitiveValue = super.encodeField(db, fieldName, value,
         enforceFieldExists: false, forComparison: forComparison);
     // If superclass can't encode field, we return value here (and assume
     // it's primitive)
     // NOTE: Implicit assumption:
     // If value != null then superclass will return != null.
     // TODO: Ensure [value] is primitive in this case.
     primitiveValue ??= value;
     return primitiveValue!;
   }
 }
	// Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file
	// for details. All rights reserved. Use of this source code is governed by a
	// BSD-style license that can be found in the LICENSE file.

	part of '../../db.dart';

	/// An implementation of [ModelDB] based on model class annotations.
	///
	/// The two constructors will scan loaded dart libraries for classes with a
	/// [Kind] annotation.
	///
	/// An example on how to write a model class is:
	/// @Kind
	/// class Person extends db.Model {
	/// @StringProperty
	/// String name;
	///
	/// @IntProperty
	/// int age;
	///
	/// @DateTimeProperty
	/// DateTime dateOfBirth;
	/// }
	///
	/// These classes must either extend [Model] or [ExpandoModel]. Furthermore
	/// they must have an empty default constructor which can be used to construct
	/// model objects when doing lookups/queries from datastore.
	class ModelDBImpl implements ModelDB {
	final Map<_ModelDescription, Map<String, Property>> _modelDesc2Properties =
	{};
	final Map<String, _ModelDescription> _kind2ModelDesc = {};
	final Map<_ModelDescription, mirrors.ClassMirror> _modelDesc2ClassMirror = {};
	final Map<_ModelDescription, Type> _type2ModelDesc = {};
	final Map<Type, _ModelDescription> _modelDesc2Type = {};

	/// Initializes a new [ModelDB] from all libraries.
	///
	/// This will scan all libraries for classes with a [Kind] annotation.
	///
	/// In case an error is encountered (e.g. two model classes with the same kind
	/// name) a [StateError] will be thrown.
	ModelDBImpl() {
	// WARNING: This is O(n) of the source code, which is very bad!
	// Would be nice to have: `currentMirrorSystem().subclassesOf(Model)`
	_initialize(mirrors.currentMirrorSystem().libraries.values);
	}

	/// Initializes a new [ModelDB] from all libraries.
	///
	/// This will scan the given [librarySymbol] for classes with a [Kind]
	/// annotation.
	///
	/// In case an error is encountered (e.g. two model classes with the same kind
	/// name) a [StateError] will be thrown.
	ModelDBImpl.fromLibrary(Symbol librarySymbol) {
	_initialize([mirrors.currentMirrorSystem().findLibrary(librarySymbol)]);
	}

	/// Converts a [ds.Key] to a [Key]. The key returned will have the correct
	/// id type which is either `Key<String>` or `Key<int>`.
	@override
	Key fromDatastoreKey(ds.Key datastoreKey) {
	var namespace = Partition(datastoreKey.partition.namespace);
	var key = namespace.emptyKey;
	for (var element in datastoreKey.elements) {
	var type = _type2ModelDesc[_kind2ModelDesc[element.kind]!];
	if (type == null) {
	throw StateError(
	'Could not find a model associated with kind "${element.kind}". '
	'Please ensure a model class was annotated with '
	'`@Kind(name: "${element.kind}")`.');
	}
	final elementId = element.id;
	if (elementId is String) {
	key = key.append<String>(type, id: elementId);
	} else if (elementId is int) {
	key = key.append<int>(type, id: elementId);
	} else {
	throw StateError('Key must be either String or int, but '
	'was ${elementId.runtimeType} for key ${element.kind}');
	}
	}
	return key;
	}

	/// Converts a [Key] to a [ds.Key].
	@override
	ds.Key toDatastoreKey(Key dbKey) {
	var elements = <ds.KeyElement>[];
	var currentKey = dbKey;
	while (!currentKey.isEmpty) {
	var id = currentKey.id;

	var modelDescription = _modelDescriptionForType(currentKey.type)!;
	var kind = modelDescription.kindName(this);

	var useIntegerId = modelDescription.useIntegerId;

	if (useIntegerId && id != null && id is! int) {
	throw ArgumentError('Expected an integer id property but '
	'id was of type ${id.runtimeType}');
	}
	if (!useIntegerId && (id != null && id is! String)) {
	throw ArgumentError('Expected a string id property but '
	'id was of type ${id.runtimeType}');
	}

	elements.add(ds.KeyElement(kind, id));
	currentKey = currentKey.parent!;
	}
	var partition = currentKey._parent as Partition;
	return ds.Key(elements.reversed.toList(),
	partition: ds.Partition(partition.namespace));
	}

	/// Converts a [Model] instance to a [ds.Entity].
	@override
	ds.Entity toDatastoreEntity(Model model) {
	try {
	var modelDescription = _modelDescriptionForType(model.runtimeType)!;
	return modelDescription.encodeModel(this, model);
	} catch (error, stack) {
	throw ArgumentError('Error while encoding entity ($error, $stack).');
	}
	}

	/// Converts a [ds.Entity] to a [Model] instance.
	@override
	T? fromDatastoreEntity<T extends Model>(ds.Entity? entity) {
	if (entity == null) {
	return null;
	}
	var key = fromDatastoreKey(entity.key);
	var kind = entity.key.elements.last.kind;
	var modelDescription = _kind2ModelDesc[kind];
	if (modelDescription == null) {
	throw StateError('Trying to deserialize entity of kind '
	'$kind, but no Model class available for it.');
	}

	try {
	return modelDescription.decodeEntity<T>(this, key, entity);
	} catch (error, stack) {
	throw StateError('Error while decoding entity ($error, $stack).');
	}
	}

	/// Returns the string representation of the kind of model class [type].
	///
	/// If the model class `type` is not found it will throw an `ArgumentError`.
	@override
	String kindName(Type type) {
	var kind = _modelDesc2Type[type]?.kind;
	if (kind == null) {
	throw ArgumentError('The class $type was not associated with a kind.');
	}
	return kind;
	}

	/// Returns the name of the property corresponding to the kind [kind] and
	/// [fieldName].
	@override
	String? fieldNameToPropertyName(String kind, String fieldName) {
	var modelDescription = _kind2ModelDesc[kind];
	if (modelDescription == null) {
	throw ArgumentError('The kind "$kind" is unknown.');
	}
	return modelDescription.fieldNameToPropertyName(fieldName);
	}

	/// Converts [value] according to the [Property] named [name] in [type].
	@override
	Object? toDatastoreValue(String kind, String fieldName, Object? value,
	{bool forComparison = false}) {
	var modelDescription = _kind2ModelDesc[kind];
	if (modelDescription == null) {
	throw ArgumentError('The kind "$kind" is unknown.');
	}
	return modelDescription.encodeField(this, fieldName, value,
	forComparison: forComparison);
	}

	Iterable<_ModelDescription> get _modelDescriptions {
	return _modelDesc2Type.values;
	}

	Map<String, Property> _propertiesForModel(
	_ModelDescription modelDescription) {
	return _modelDesc2Properties[modelDescription]!;
	}

	_ModelDescription? _modelDescriptionForType(Type? type) {
	return _modelDesc2Type[type!];
	}

	mirrors.ClassMirror? _modelClass(_ModelDescription md) {
	return _modelDesc2ClassMirror[md];
	}

	void _initialize(Iterable<mirrors.LibraryMirror> libraries) {
	for (var lm in libraries) {
	lm.declarations.values
	.whereType<mirrors.ClassMirror>()
	.where((d) => d.hasReflectedType)
	.forEach(_tryLoadNewModelClass);
	}

	// Ask every [ModelDescription] to compute whatever global state it wants
	// to have.
	for (var modelDescription in _modelDescriptions) {
	modelDescription.initialize(this);
	}

	// Ask every [ModelDescription] whether we should register it with a given
	// kind name.
	for (var modelDescription in _modelDescriptions) {
	var kindName = modelDescription.kindName(this);
	if (_kind2ModelDesc.containsKey(kindName)) {
	throw StateError('Cannot have two ModelDescriptions '
	'with the same kind ($kindName)');
	}
	_kind2ModelDesc[kindName] = modelDescription;
	}
	}

	void _tryLoadNewModelClass(mirrors.ClassMirror classMirror) {
	Kind? kindAnnotation;
	for (var instance in classMirror.metadata) {
	if ((instance.reflectee as Object).runtimeType == Kind) {
	if (kindAnnotation != null) {
	throw StateError(
	'Cannot have more than one ModelMetadata() annotation '
	'on a Model class');
	}
	kindAnnotation = instance.reflectee as Kind?;
	}
	}

	if (kindAnnotation != null) {
	var name = kindAnnotation.name;
	var integerId = kindAnnotation.idType == IdType.Integer;
	var stringId = kindAnnotation.idType == IdType.String;

	// Fall back to the class name.
	name ??= mirrors.MirrorSystem.getName(classMirror.simpleName);

	// This constraint should be guaranteed by the Kind() const constructor.
	assert((integerId && !stringId) \|\| (!integerId && stringId));

	_tryLoadNewModelClassFull(classMirror, name, integerId);
	}
	}

	static bool _isRequiredAnnotation(mirrors.InstanceMirror annotation) {
	return annotation.type.simpleName == #Required;
	}

	/// Returns true if a constructor invocation is valid even if the specified
	/// [parameter] is omitted.
	///
	/// This is true for named parameters, optional parameters, and parameters
	/// with a default value.
	static bool _canBeOmitted(mirrors.ParameterMirror parameter) {
	if (parameter.metadata.any(_isRequiredAnnotation)) {
	return false;
	}
	return parameter.isOptional \|\|
	parameter.isNamed \|\|
	parameter.hasDefaultValue;
	}

	/// Returns true if the specified [classMirror] has a default (unnamed)
	/// constructor that accepts an empty arguments list.
	@visibleForTesting
	static bool hasDefaultConstructor(mirrors.ClassMirror classMirror) {
	for (var declaration in classMirror.declarations.values) {
	if (declaration is mirrors.MethodMirror) {
	if (declaration.isConstructor &&
	declaration.constructorName == const Symbol('') &&
	declaration.parameters.every(_canBeOmitted)) {
	return true;
	}
	}
	}
	return false;
	}

	void _tryLoadNewModelClassFull(
	mirrors.ClassMirror modelClass, String name, bool useIntegerId) {
	assert(!_modelDesc2Type.containsKey(modelClass.reflectedType));

	_ModelDescription modelDesc;
	if (_isExpandoClass(modelClass)) {
	modelDesc = _ExpandoModelDescription(name, useIntegerId);
	} else {
	modelDesc = _ModelDescription(name, useIntegerId);
	}

	_type2ModelDesc[modelDesc] = modelClass.reflectedType;
	_modelDesc2Type[modelClass.reflectedType] = modelDesc;
	_modelDesc2ClassMirror[modelDesc] = modelClass;
	_modelDesc2Properties[modelDesc] =
	_propertiesFromModelDescription(modelClass);

	// Ensure we have an empty constructor.
	if (!hasDefaultConstructor(modelClass)) {
	throw StateError('Class ${modelClass.simpleName} does not have a default '
	'constructor.');
	}
	}

	Map<String, Property> _propertiesFromModelDescription(
	mirrors.ClassMirror modelClassMirror) {
	var properties = <String, Property>{};
	var propertyNames = <String>{};

	// Loop over all classes in the inheritance path up to the Object class.
	while (modelClassMirror.superclass != null) {
	var memberMap = modelClassMirror.instanceMembers;
	// Loop over all declarations (which includes fields)
	modelClassMirror.declarations
	.forEach((Symbol fieldSymbol, mirrors.DeclarationMirror decl) {
	// Look if the symbol is a getter and we have metadata attached to it.
	if (memberMap.containsKey(fieldSymbol) &&
	memberMap[fieldSymbol]!.isGetter) {
	final propertyAnnotations = decl.metadata
	.map((mirrors.InstanceMirror mirror) => mirror.reflectee)
	.whereType<Property>()
	.toList();

	if (propertyAnnotations.length > 1) {
	throw StateError(
	'Cannot have more than one Property annotation on a model '
	'field.');
	} else if (propertyAnnotations.length == 1) {
	var property = propertyAnnotations.first;

	// Get a String representation of the field and the value.
	var fieldName = mirrors.MirrorSystem.getName(fieldSymbol);

	// Determine the name to use for the property in datastore.
	var propertyName = property.propertyName;
	propertyName ??= fieldName;

	if (properties.containsKey(fieldName)) {
	throw StateError(
	'Cannot have two Property objects describing the same field '
	'in a model object class hierarchy.');
	}

	if (propertyNames.contains(propertyName)) {
	throw StateError(
	'Cannot have two Property objects mapping to the same '
	'datastore property name "$propertyName".');
	}
	properties[fieldName] = property;
	propertyNames.add(propertyName);
	}
	}
	});
	modelClassMirror = modelClassMirror.superclass!;
	}

	return properties;
	}

	final _originalExpandoModelClass = mirrors.reflectClass(ExpandoModel);
	final _originalModelClass = mirrors.reflectClass(Model);

	bool _isExpandoClass(mirrors.ClassMirror? modelClass) {
	while (modelClass != null && modelClass.superclass != modelClass) {
	if (modelClass.originalDeclaration == _originalExpandoModelClass) {
	return true;
	} else if (modelClass.originalDeclaration == _originalModelClass) {
	return false;
	}

	modelClass = modelClass.superclass;
	}
	throw StateError('This should be unreachable.');
	}
	}

	class _ModelDescription<T extends Model> {
	final HashMap<String, String> _property2FieldName = HashMap<String, String>();
	final HashMap<String, String> _field2PropertyName = HashMap<String, String>();
	final Set<String> _indexedProperties = <String>{};
	final Set<String> _unIndexedProperties = <String>{};

	final String kind;
	final bool useIntegerId;

	_ModelDescription(this.kind, this.useIntegerId);

	void initialize(ModelDBImpl db) {
	// Compute propertyName -> fieldName mapping.
	db._propertiesForModel(this).forEach((String fieldName, Property prop) {
	// The default of a datastore property name is the fieldName.
	// It can be overridden with [Property.propertyName].
	var propertyName = prop.propertyName;
	propertyName ??= fieldName;

	_property2FieldName[propertyName] = fieldName;
	_field2PropertyName[fieldName] = propertyName;
	});

	// Compute properties & unindexed properties
	db._propertiesForModel(this).forEach((String fieldName, Property prop) {
	var propertyName = prop.propertyName;
	propertyName ??= fieldName;

	if (prop.indexed) {
	_indexedProperties.add(propertyName);
	} else {
	_unIndexedProperties.add(propertyName);
	}
	});
	}

	String kindName(ModelDBImpl db) => kind;

	ds.Entity encodeModel(ModelDBImpl db, T model) {
	var key = db.toDatastoreKey(model.key);

	var properties = <String, Object?>{};
	var mirror = mirrors.reflect(model);

	db._propertiesForModel(this).forEach((String fieldName, Property prop) {
	_encodeProperty(db, model, mirror, properties, fieldName, prop);
	});

	return ds.Entity(key, properties,
	unIndexedProperties: _unIndexedProperties);
	}

	void _encodeProperty(
	ModelDBImpl db,
	Model model,
	mirrors.InstanceMirror mirror,
	Map properties,
	String fieldName,
	Property prop) {
	var propertyName = prop.propertyName;
	propertyName ??= fieldName;

	var value =
	mirror.getField(mirrors.MirrorSystem.getSymbol(fieldName)).reflectee;
	if (!prop.validate(db, value)) {
	throw StateError('Property validation failed for '
	'property $fieldName while trying to serialize entity of kind '
	'${model.runtimeType}. ');
	}
	properties[propertyName] = prop.encodeValue(db, value);
	}

	H decodeEntity<H extends Model>(ModelDBImpl db, Key key, ds.Entity entity) {
	// NOTE: this assumes a default constructor for the model classes!
	var classMirror = db._modelClass(this)!;
	var mirror = classMirror.newInstance(const Symbol(''), []);

	// Set the id and the parent key
	final model = mirror.reflectee as Model;
	model.id = key.id;
	model.parentKey = key.parent;

	db._propertiesForModel(this).forEach((String fieldName, Property prop) {
	_decodeProperty(db, entity, mirror, fieldName, prop);
	});
	return mirror.reflectee as H;
	}

	void _decodeProperty(ModelDBImpl db, ds.Entity entity,
	mirrors.InstanceMirror mirror, String fieldName, Property prop) {
	var propertyName = fieldNameToPropertyName(fieldName);

	var rawValue = entity.properties[propertyName!];
	var value = prop.decodePrimitiveValue(db, rawValue);

	if (!prop.validate(db, value)) {
	throw StateError('Property validation failed while '
	'trying to deserialize entity of kind '
	'${entity.key.elements.last.kind} (property name: $propertyName)');
	}

	try {
	mirror.setField(mirrors.MirrorSystem.getSymbol(fieldName), value);
	// ignore: avoid_catching_errors
	} on TypeError catch (error) {
	throw StateError(
	'Error trying to set property "${prop.propertyName}" '
	'to $value for field "$fieldName": $error',
	);
	}
	}

	String? fieldNameToPropertyName(String fieldName) {
	return _field2PropertyName[fieldName];
	}

	String? propertyNameToFieldName(ModelDBImpl db, String propertySearchName) {
	return _property2FieldName[propertySearchName];
	}

	Object? encodeField(ModelDBImpl db, String fieldName, Object? value,
	{bool enforceFieldExists = true, bool forComparison = false}) {
	var property = db._propertiesForModel(this)[fieldName];
	if (property != null) {
	return property.encodeValue(db, value, forComparison: forComparison);
	}
	if (enforceFieldExists) {
	throw ArgumentError(
	'A field named "$fieldName" does not exist in kind "$kind".');
	}
	return null;
	}
	}

	// NOTE/TODO:
	// Currently expanded properties are only
	// * decoded if there are no clashes in [usedNames]
	// * encoded if there are no clashes in [usedNames]
	// We might want to throw an error if there are clashes, because otherwise
	// - we may end up removing properties after a read-write cycle
	// - we may end up dropping added properties in a write
	// ([usedNames] := [realFieldNames] + [realPropertyNames])
	class _ExpandoModelDescription extends _ModelDescription<ExpandoModel> {
	late Set<String> realFieldNames;
	late Set<String> realPropertyNames;
	late Set<String> usedNames;

	_ExpandoModelDescription(String kind, bool useIntegerId)
	: super(kind, useIntegerId);

	@override
	void initialize(ModelDBImpl db) {
	super.initialize(db);

	realFieldNames = Set<String>.from(_field2PropertyName.keys);
	realPropertyNames = Set<String>.from(_property2FieldName.keys);
	usedNames = <String>{}
	..addAll(realFieldNames)
	..addAll(realPropertyNames);
	}

	@override
	ds.Entity encodeModel(ModelDBImpl db, ExpandoModel model) {
	var entity = super.encodeModel(db, model);
	var properties = entity.properties;
	model.additionalProperties.forEach((String key, Object? value) {
	// NOTE: All expanded properties will be indexed.
	if (!usedNames.contains(key)) {
	properties[key] = value;
	}
	});
	return entity;
	}

	@override
	T decodeEntity<T extends Model>(ModelDBImpl db, Key key, ds.Entity entity) {
	var model = super.decodeEntity(db, key, entity) as ExpandoModel;
	var properties = entity.properties;
	properties.forEach((String key, Object? value) {
	if (!usedNames.contains(key)) {
	model.additionalProperties[key] = value;
	}
	});
	// TODO: check if there is a more elegant solution than this
	return model as T;
	}

	@override
	String fieldNameToPropertyName(String fieldName) {
	var propertyName = super.fieldNameToPropertyName(fieldName);
	// If the ModelDescription doesn't know about [fieldName], it's an
	// expanded property, where propertyName == fieldName.
	propertyName ??= fieldName;
	return propertyName;
	}

	@override
	String propertyNameToFieldName(ModelDBImpl db, String propertyName) {
	var fieldName = super.propertyNameToFieldName(db, propertyName);
	// If the ModelDescription doesn't know about [propertyName], it's an
	// expanded property, where propertyName == fieldName.
	fieldName ??= propertyName;
	return fieldName;
	}

	@override
	Object encodeField(ModelDBImpl db, String fieldName, Object? value,
	{bool enforceFieldExists = true, bool forComparison = false}) {
	// The [enforceFieldExists] argument is intentionally ignored.

	var primitiveValue = super.encodeField(db, fieldName, value,
	enforceFieldExists: false, forComparison: forComparison);
	// If superclass can't encode field, we return value here (and assume
	// it's primitive)
	// NOTE: Implicit assumption:
	// If value != null then superclass will return != null.
	// TODO: Ensure [value] is primitive in this case.
	primitiveValue ??= value;
	return primitiveValue!;
	}
	}