Improving documentation
This commit is contained in:
parent
fde6362174
commit
a0b98ee6d6
|
|
@ -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
|
||||
|
||||
.. 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;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue