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
|
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.
|
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