RdfGlobalResource class

Marks a Dart class as an RDF resource with a global IRI.

This annotation provides a declarative way to indicate that instances of this class should be mapped to RDF subjects with specific IRIs. When using the annotation, a mapper is either generated automatically based on the annotation or you can implement a custom mapper manually.

Note that manually implemented and registered mappers don't require this annotation at all - you can map any class to RDF by implementing the appropriate mapper interface and registering an instance with the RdfMapper facade.

When using the standard constructor (@RdfGlobalResource(classIri, iriStrategy)), a mapper is automatically generated based on the property annotations (like @RdfProperty) in your class. By default, this mapper is registered within initRdfMapper (when registerGlobally is true). This generated mapper will create RDF triples with the instance's IRI as the subject for each annotated property.

Set registerGlobally to false if this mapper should not be registered automatically. This is useful when the mapper requires constructor parameters that are only available at runtime and should be provided via @RdfProvides annotations in the parent class.

The instance's IRI is computed using the provided iriStrategy (please refer to the @RdfIri documentation for details on how IRIs are constructed).

With custom mappers, the actual RDF triple generation depends on your mapper implementation, regardless of any property annotations.

Global resources represent entities with unique identifiers that can be referenced directly by other entities in the RDF graph.

You can use this annotation in several ways, depending on your mapping needs:

1. Standard: Use @RdfGlobalResource(classIri, iriStrategy) with an IRI template - the mapper is automatically generated and registered within initRdfMapper
2. Deserialize-only: Use @RdfGlobalResource.deserializeOnly(classIri) - generates a mapper that only deserializes from RDF (IRI strategy not needed)
3. Serialize-only: Use @RdfGlobalResource.serializeOnly(classIri, iriStrategy) - generates a mapper that only serializes to RDF
4. Named mapper: Use @RdfGlobalResource.namedMapper() - you must implement the mapper, instantiate it, and provide it to initRdfMapper as a named parameter
5. Mapper type: Use @RdfGlobalResource.mapper() - you must implement the mapper, it will be instantiated and registered within initRdfMapper automatically
6. Mapper instance: Use @RdfGlobalResource.mapperInstance() - you must implement the mapper, your instance will be registered within initRdfMapper automatically

This annotation is typically used for:

• Domain entities with unique identifiers
• Resources that need to be referenced from multiple places
• Top-level objects in your data model
• Entities that might be referenced by external systems

Note: Besides using this annotation at the class level, you can also use GlobalResourceMapping as a parameter in the @RdfProperty annotation with the globalResource parameter. This allows you to specify custom mappers for specific relationships, overriding the globally registered mapper. This is especially useful when you need different mapping behaviors for the same type depending on the context where it's used. See RdfProperty.globalResource for more details and examples.

Example with IRI template:

// Define a book with a globally unique IRI pattern
@RdfGlobalResource(SchemaBook.classIri, IriStrategy('http://example.org/book/{id}'))
class Book {
  @RdfIriPart('id')
  final String id;

  @RdfProperty(SchemaBook.name)
  final String title;

  @RdfProperty(SchemaBook.author)
  final Person author;
  // ...
}

Example with custom named mapper:

@RdfGlobalResource.namedMapper('customBookMapper')
class Book {
  // ...
}

// Generated initRdfMapper function will have a parameter:
initRdfMapper({
  required GlobalResourceMapper<Book> customBookMapper,
  // other parameters...
}) { ... }