From a0b98ee6d68dd0b2e0dc581a2b8314554b79c062 Mon Sep 17 00:00:00 2001 From: Luca Frosini Date: Mon, 24 Jun 2024 14:38:27 +0200 Subject: [PATCH] Improving documentation --- docs/update-type-definition-guideline.rst | 262 +++++++++++++++++++++- 1 file changed, 261 insertions(+), 1 deletion(-) diff --git a/docs/update-type-definition-guideline.rst b/docs/update-type-definition-guideline.rst index be5f28a..0a83377 100644 --- a/docs/update-type-definition-guideline.rst +++ b/docs/update-type-definition-guideline.rst @@ -577,4 +577,264 @@ which will be serialized in turn as: The problem of this solution is that if the facet is updated to the new format in the server and there are old clients they will not be able to deserialise the new version. -This \ No newline at end of file + +.. code:: java + + import java.util.Date; + + import org.gcube.com.fasterxml.jackson.databind.annotation.JsonDeserialize; + import org.gcube.informationsystem.model.reference.entities.Facet; + import org.gcube.informationsystem.model.reference.properties.Event; + import org.gcube.informationsystem.types.annotations.ISProperty; + import org.gcube.informationsystem.types.reference.Change; + import org.gcube.informationsystem.types.reference.Changelog; + import org.gcube.informationsystem.types.reference.TypeMetadata; + import org.gcube.informationsystem.utils.Version; + import org.gcube.resourcemanagement.model.impl.entities.facets.EventFacetImpl; + + /** + * EventFacet captures information on a certain event/happening characterising the life cycle of the resource. + * + * Examples of an event are the start time of a virtual machine or the activation time of an electronic service. + * + * https://wiki.gcube-system.org/gcube/GCube_Model#Event_Facet + * + * @author Luca Frosini (ISTI - CNR) + */ + @JsonDeserialize(as=EventFacetImpl.class) + @TypeMetadata( + name = EventFacet.NAME, + description = "EventFacet captures information on a certain event/happening characterising the life cycle of the resource. " + + "Examples of an event are the start time of a virtual machine or the activation time of an electronic service.", + version = EventFacet.VERSION + ) + @Changelog ({ + @Change(version = EventFacet.VERSION, description = "Switching to {@link Event} Property added in the information-system-model"), + @Change(version = Version.MINIMAL_VERSION_STRING, description = Version.MINIMAL_VERSION_DESCRIPTION) + }) + public interface EventFacet extends Facet { + + public static final String NAME = "EventFacet"; // EventFacet.class.getSimpleName(); + public static final String VERSION = "2.0.0"; + + public static final String EVENT_PROPERTY = "theEvent"; + + @Deprecated + /** + * This method will be removed soon. + * Use {@link EventFacet#getTheEvent()} method which return {@link Event} instance. + * The date can be retrieved by using {@link Event#getWhen()} method. + * + * @return the date of the occurred event. + */ + public Date getDate(); + + @Deprecated + /** + * This method will be removed soon. + * Use {@link EventFacet#setEvent(Event event)}. + * The date can be set in {@link Event} instance by using + * {@link Event#setWhen(Date date)} method. + * + * @param date the date of the occurred event. + * which is the same of the 'when' Date of the {@link Event} instance. + */ + public void setDate(Date date); + + @Deprecated + /** + * This method will be removed soon. + * Use {@link EventFacet#getTheEvent()} method which return {@link Event} instance. + * The deprecated 'event' String can be retrieved by using {@link Event#getWhat()} method. + * + * @return the string of event, e.g. active + */ + public String getEvent(); + + @Deprecated + /** + * This method will be removed soon. + * Use {@link EventFacet#setEvent(Event event)}. + * The deprecated 'event' String can be set in {@link Event} instance by using + * {@link Event#setWhat(String what)} method. + * + * @param event the string of the event to set, e.g. failed + * which is the same of the 'what' String of the {@link Event} instance. + */ + public void setEvent(String event); + + /** + * Actually is not mandatory for backward compatibility. + * In the next version this method will be deprecated to and it will be replaced + * by a method with the following signature + * + * public Event getEvent() + * + * This is not actually possible because we need to maintain + * {@link EventFacet#getEvent()} for backward compatibility + * + * @return the event + */ + @ISProperty(name=EVENT_PROPERTY, description = "The event eventually described by the five W (What, When, Who, Where, Why)", mandatory=false, nullable=false) + public Event getTheEvent(); + + /** + * Set the event + * @param event the event to set + */ + public void setEvent(Event event); + + } + +With the following definition + +.. code:: javascript + + { + "type": "FacetType", + "id": "b76de0ac-048a-43a0-ae4f-e3fdb1a7d27c", + "name": "EventFacet", + "description": "EventFacet captures information on a certain event/happening characterising the life cycle of the resource. Examples of an event are the start time of a virtual machine or the activation time of an electronic service.", + "properties": + [ + { + "type": "PropertyDefinition", + "name": "theEvent", + "description": "The event eventually described by the five W (What, When, Who, Where, Why)", + "mandatory": false, + "readonly": false, + "notnull": true, + "max": null, + "min": null, + "regexp": null, + "defaultValue": null, + "propertyType": "Event" + } + ], + "version": "2.0.0", + "changelog": { + "2.0.0": "Switching to {@link Event} Property added in the information-system-model", + "1.0.0": "First Version" + }, + "abstract": false, + "final": false, + "extendedTypes": [ "Facet" ] + } + + + +The implementation should be the following: + + +.. code:: java + + import java.util.Date; + + import org.gcube.com.fasterxml.jackson.annotation.JsonGetter; + import org.gcube.com.fasterxml.jackson.annotation.JsonIgnore; + import org.gcube.com.fasterxml.jackson.annotation.JsonSetter; + import org.gcube.com.fasterxml.jackson.annotation.JsonTypeName; + import org.gcube.informationsystem.model.impl.entities.FacetImpl; + import org.gcube.informationsystem.model.impl.properties.EventImpl; + import org.gcube.informationsystem.model.reference.properties.Event; + import org.gcube.resourcemanagement.model.reference.entities.facets.EventFacet; + + /** + * @author Luca Frosini (ISTI - CNR) + */ + @JsonTypeName(value = EventFacet.NAME) + public class EventFacetImpl extends FacetImpl implements EventFacet { + + /** + * Generated Serial version UID + */ + private static final long serialVersionUID = -4130548762073254058L; + + protected Event theEvent; + + @Override + @Deprecated + /** + * {@inheritDoc} + * + * This function is actually a shortcut to + * {@link EventFacet#getTheEvent()}.{@link Event#getWhen()} + */ + public Date getDate() { + if(theEvent==null) { + return null; + } + return theEvent.getWhen(); + } + + @Override + @Deprecated + /** + * {@inheritDoc} + * + * This function is actually a shortcut to + * {@link EventFacet#getTheEvent()}.{@link Event#setWhen(Date date)} + * + * It eventually instantiate {@link Event} if null. + */ + @JsonSetter("date") + public void setDate(Date date) { + if(theEvent == null) { + theEvent = new EventImpl(); + } + theEvent.setWhen(date); + } + + @Override + @Deprecated + /** + * {@inheritDoc} + * + * This function is actually a shortcut to + * {@link EventFacet#getTheEvent()}.{@link Event#getWhat()} + */ + public String getEvent() { + if(theEvent==null) { + return null; + } + return theEvent.getWhat(); + } + + @Override + @Deprecated + /** + * {@inheritDoc} + * + * This function is actually a shortcut to + * {@link EventFacet#getTheEvent()}.{@link Event#setWhat(String what)}. + * + * It eventually instantiate {@link Event} if null. + */ + public void setEvent(String event) { + if(event == null) { + this.theEvent = new EventImpl(); + } + this.theEvent.setWhat(event); + } + + @Override + /** + * {@inheritDoc} + */ + @JsonGetter(EventFacet.EVENT_PROPERTY) + public Event getTheEvent() { + return theEvent; + } + + @Override + /** + * {@inheritDoc} + */ + @JsonIgnore + @JsonSetter(EventFacet.EVENT_PROPERTY) + public void setEvent(Event event) { + this.theEvent = event; + } + + } +