Description of the Supported Metadata Annotations

D4.1–DescriptionoftheSupportedMetadataAnnotations

1/32

DeliverableD4.1

DescriptionoftheSupportedMetadataAnnotations

Editor(s): PanagiotisGouvas

ResponsibleOrganization(s): UbitechLtd

Version: 1.00

Status: Final

Date: 13/06/2016

Disseminationlevel: Public

Ref. Ares(2016)2768135 - 14/06/2016

2/32

Deliverablefactsheet

GrantAgreementNo.: 645372

ProjectAcronym: ARCADIA

ProjectTitle: A novel reconfigurAble by design highly distRibuted appliCAtionsDevelopmentparadIgmoverprogrAmmableinfrastructure

ProjectWebsite: http://www.arcadia-framework.eu/

StartDate: 01/01/2015

Duration: 36months

TitleofDeliverable: D4.1DescriptionoftheSupportedMetadataAnnotations

RelatedWP: WP4–ARCADIADevelopmentToolkit

Duedateaccordingtocontract: 31/03/2016

Editor(s): PanagiotisGouvas

Contributor(s): ConstantinosVassilakis, Eleni Fotopoulou,AnastasiosZafeiropoulos(UBITECH)

AlessandroRossini(SINTEF)

NikosKoutsouris(WINGS)

GeorgeKioumourtzis(ADITESS)

Reviewer(s): NikosKoutsouris(WINGS)


Approvedby: AllPartners

Abstract: Thisdeliverableprovidesadescriptionofthemetadata/annotationsthat are supported by the ARCADIA software developmentparadigm,basedontheidentifiedrequirementsinWP2.

Keyword(s): Microservice Development, Application Lifecycle Management,Annotations

3/32

Partners

Insight Centre for Data Analyt ics, National University of Ire land, Galway

Ireland

St iftelsen SINTEF Norway

Technische Universität Berl in Germany

Consorzio Nazionale Interuniversitar io per le Telecomunicazioni

Ita ly

Univerza v L jubl jani S lovenia

UBITECH Greece

WINGS ICT Solutions Information & Communication Technologies EPE

Greece

MAGGIOLI SPA Italy

ADITESS Advanced Integrated Technology Solut ions and Services Ltd

Cyprus

5/32

RevisionHistoryVersion Date Editor(s) Remark(s)0.1 01/03/2016 PanagiotisGouvas(UBITECH) DefiningToC

0.2 20/04/2016 PanagiotisGouvas(UBITECH)

AnastasiosZafeiropoulos(UBITECH)




Firstversionwithinputsfrompartners

0.3 17/05/2016 PanagiotisGouvas(UBITECH)

Eleni Fotopoulou, ConstantinosVassilakis(UBITECH)




Additions to all chapters and consolidatedversion

0.4 30/05/2016 NikosKoutsouris(WINGS)


Internalreview

1.0 13/06/2016 PanagiotisGouvas(UBITECH) Final version taking into account internalreviewcomments

6/32

Statementoforiginality:

This deliverable contains original unpublished work except where clearly indicated otherwise.Acknowledgementofpreviouslypublishedmaterialandof theworkofothershasbeenmade throughappropriatecitation,quotationorboth.

7/32

ExecutiveSummaryARCADIA aims to provide a novel reconfigurable-by-design highly-distributed applications (a.k.a. HDAs)

development paradigm over programmable cloud infrastructure. Such a novel development paradigm is

neededtotakeadvantageoftheemergingprogrammabilityofthecloudinfrastructure,andhencedevelop

reconfigurable-by-design applications that support high performance, scalability, failure prevention and

recovery, and in general self-adaptation to changes in the execution environment. The services that

comprise an HDA should support a specific set of characteristics in order to take full advantage of the

underlyingprogrammabilitylayer.Morespecifically,thereareatleasteightfunctionalcharacteristicsthat

shouldbemet.Accordingtothese,anyservicethattakespartinanHDAshould:

a. exposeitsconfigurationparametersalongwiththeirmetadata;

b. exposechainableinterfaceswhichwillbeusedbyothernativeapplicationsinordertocreateaservice

graph;

c. exposerequiredinterfaceswhichwillbealsousedduringthecreationofaservicegraph;

d. exposequantitativemetricsregardingtheQoSofthenativeapplication;

e. encapsulatealifecycle-managementprogrammabilitylayerwhichwillbeusedduringtheplacementof

oneservicegraphintheinfrastructuralresources;

f. bestatelessinordertobehorizontallyscalablebydesign;

g. bereactivetoruntimemodificationofofferedresourcesinordertobeverticallyscalablebydesign;

h. beagnostictophysicalstorage,networkandgeneralpurposeresources.

IntheframeofARCADIAtheHDAscanbeeitherLegacyapplications,whichareexistingapplicationsthat

arealreadyavailableinanexecutableformatandhavetobeorchestratedbytheARCADIAOrchestrator;or

Native ARCADIA applications,which benefit from the full set of capabilities of the framework or Hybrid

applications that consist of application tiers from both cases above. The purpose of the ARCADIA

annotationframework-asdescribedinthecurrentmanuscript-istomakeuseoftheextensibilityfeatures

ofmodernprogramminglanguagesandcomeupwithspecificsetsofannotationsthatwillbeusedduring

runtime in order to automate at a big extend the business logic that relates to the aforementioned

characteristics. Therefore, ARCADIA makes use of JAVA’s extensibility mechanisms namely; “JSR-175: A

Metadata Facility for the Java Programming Language”1 and “JSR-269: Pluggable Annotation Processing

API”2 to provide a set of annotations that automatically invoke runtime handlers related to component

1https://jcp.org/en/jsr/detail?id=1752https://jcp.org/en/jsr/detail?id=269

8/32

management,configurationmanagement,managementofperformancemetrics,managementof lifecycle

andmanagementofdependencies.

9/32

TableofContentsEXECUTIVESUMMARY................................................................................................................................................................7

TABLEOFCONTENTS..................................................................................................................................................................9

LISTOFFIGURES........................................................................................................................................................................10

1 INTRODUCTION................................................................................................................................................................11

1.1 PURPOSEANDSCOPE..........................................................................................................................................................................11

2 THEROLEOFTHEARCADIAANNOTATIONS...........................................................................................................12

2.1 NATIVEARCADIAAPPLICATIONSANDTHEIRLIFECYCLE.........................................................................................................122.2 WHYANANNOTATIONFRAMEWORK?............................................................................................................................................15

3 ARCADIAANNOTATIONS...............................................................................................................................................17

3.1 COMPONENTMANAGEMENT.............................................................................................................................................................173.2 CONFIGURATIONMANAGEMENT......................................................................................................................................................193.3 COMPONENT’SMETRICS....................................................................................................................................................................203.4 LIFECYCLEMANAGEMENT.................................................................................................................................................................223.5 DEPENDENCYMANAGEMENT...........................................................................................................................................................23

4 USAGEOFANNOTATIONS..............................................................................................................................................25

4.1 ARCADIAWEB-BASEDIDEENVIRONMENT.................................................................................................................................254.2 VALIDATIONOFANNOTATIONS&GENERATIONOFTHINLAYER................................................................................................26

5 CONCLUSIONS....................................................................................................................................................................29

REFERENCES................................................................................................................................................................................30

ANNEXI–SAMPLEANNOTATEDCOMPONENT................................................................................................................31

10/32

ListofFiguresFigure1-(a)HDAIndicativeBreakdown,(b)HDAhorizontalscaling............................................................13Figure2-OverviewofARCADIAAnnotations................................................................................................17Figure3-ArcadiaComponentAnnotation......................................................................................................18Figure4-SerializationModelforaspecificcomponent................................................................................19Figure5–ConfigurationParameterAnnotation..............................................................................................20Figure6–ArcadiaMetricAnnotation..............................................................................................................21Figure7–ArcadiaMetricsAnnotation.............................................................................................................21Figure8–LifecycleInitializeAnnotation..........................................................................................................22Figure9–LifecycleStartAnnotation................................................................................................................23Figure10–LifecycleStopAnnotation..............................................................................................................23Figure11–DependencyExportAnnotation....................................................................................................24Figure12–DependencyResolutionHandlerAnnotation.................................................................................24Figure13–DevelopmentofARCADIAcomponentthroughweb-basedIDE..................................................26Figure14–MavenmodulethatperformstheAnnotationintrospection.......................................................27

11/32

1 Introduction

1.1 PurposeandScope

This document provides a description of the ARCADIA annotation framework that will be used for the

developmentofHighlyDistributedApplications.Theannotationsareformallyanelegantfeatureofmodern

programminglanguages(e.g.JavaandC#)thatallowdevelopersto‘decorate’theirprogramswithspecific

tags(i.e.theannotations).Thisdecorationprovidestothedevelopedprogramspecificfunctionalitywhich

is either design-time (i.e. during compilation) or run-time (i.e. during execution). This functionality may

span to different aspects such as automated code generation, automated injection of business logic,

design-timevalidationetc.

As alreadymentioned, ARCADIA aims to provide a novel reconfigurable-by-design and highly-distributed

applications development paradigm over programmable cloud infrastructure. Such a novel development

paradigm isneeded to takeadvantageof theemergingprogrammabilityof the cloud infrastructure, and

hence develop reconfigurable-by-design applications that support high performance, scalability, failure

preventionandrecovery,andingeneralself-adaptationtochangesintheexecutionenvironment.Tothis

end, the annotation framework is the cornerstone framework that is utilised in order to implement the

developmentparadigm.

Thepurposeofthisdeliverableistoelaborate,ontheonehand,ontheexactannotationsthathavebeen

designedandon theotherhand,on thebusiness logic that isbound to theseannotations. Thebusiness

logicistailoredtothefunctionalrequirementsofHDAs.Therefore,Chapter2isdevotedontheanalysisof

the exact characteristics that HDA have and how these characteristics can be addressed using an

annotationframework.

Chapter3providesthecoreanalysisof theannotations.Theannotationsare functionallygrouped in five

categoriesaccordingtothenatureofthebusinesslogicthatisboundtotheusageoftheannotation.These

categories include component management, configuration management, management of performance

metrics, management of lifecycle, and management of dependencies. For each of these categories the

exactbusinesslogicisdiscussed.WediscussinChapter4,theusageoftheannotationframeworkthrough

theARCADIAIDE,whichisunderdevelopment.Finally,Chapter5concludesthedeliverable.

12/32

2 TheRoleoftheARCADIAAnnotationsARCADIAaimstoprovideaprogrammingparadigmforHighlyDistributedApplications(a.k.a.HDAs).Such

applicationsare theones thatarebuilt inorder to runonmulti-cloud infrastructure.Thestructureofan

HDA enables high flexibility in reusing and composingbasic services such as databases, web front-end,

authentication modules, network functions and the like. To this end, according to the architectural

deliverable [2], the following application types can be defined: a) Legacy applications that are existing

applicationsthatarealreadyavailableinanexecutableformatandhavetobeorchestratedbytheARCADIA

Orchestrator;b)NativeARCADIAapplicationsthatbenefitfromthefullsetofcapabilitiesoftheframework

andc)Hybridapplicationsthatconsistofapplicationtiersfromboththecasesabove.

ThepurposeofthisdeliverableistoelaborateontheARCADIAannotationsthatareusedinordertocreate

native ARCADIA applications. The other two types of HDAs may be functional equivalent to the native

ARCADIA applications if someone undertakes the task of creating thin wrappers that emulate the

functionalities that is automaticallyofferedby thenativeapps. Therefore, the reasonablequestions that

areraisedarethefollowing:a)whatarethefunctionalcharacteristicsofanARCADIAnativeapplication?b)

whatwasthereasonbehindthearchitecturalchoiceofcode-levelannotations?Thefollowingsectionswill

shedlightregardingbothofthesequestions.

2.1 NativeARCADIAApplicationsandtheirLifecycleAs already discussed, a Highly Distributed Application (HDA) is defined as a reconfigurable-by-design

distributedscalablestructuredsystemofsoftwareentitiesconstructedtoillustrateanetworkservicewhen

implemented to run over a programmable cloud infrastructure. A HDA is a multi-tier cloud application

consistingofapplication’stierschainedwithothersoftwareentitiesillustratingnetworkfunctionsapplied

tothenetworktraffictowards/fromandbetweenapplication’stiers.Theterm‘reconfigurable-by-design’

maybeconsideredasanextensionoftheterm‘contextawareadaptable’[5].AHDAnotonlyisdesignedto

be context-aware, able to adapt its processes to the contextbut also is able to reconfigure its structure

accordingly,shareitscontextandenableprogrammabilitythroughexposingaprogramminginterface.

Thus,aHDAmayexpandorshrinkbysupportinghorizontalscaling(outandin)foreachsoftwareentityin

theservicechainwhilemayreform(change itsstructure)by includingorexcludingsoftwarecomponents

from the chain and/or change routing among themasneeded.AHDAmayexpose its context and state

while it may provide a programmable interface for communication and externally being adapted and

configured or re-used as a component of other HDAs. Each Application tier of a HDA is a distinct

application-specificlogicaloperationlayer.EachothersoftwareentityinvolvedintheApplication’schainis

aVirtual Function (VF) specific logical operation layer. EachApplication tier andother involved software

13/32

entityprovide/exposetoeachotheraBinding Interface(hereinafterBI) lettingeachotherhaveaccessto

providedfunctionalitiesandsupportingcommunication.

WhiledevelopinganApplicationTier, it isnecessarytohaveknowledgeoftheBIofeveryothersoftware

component whose functionalities are required to be utilized within this Application Tier. Recursively, a

componentofaHDAchainmayalsobeachain itself;analreadydevelopedHDAoraVFchainexposing

requiredfunctionalities.Thereisnoneedtocommunicatewitheverycomponentofthenestedchainbut

withaServiceBindingInterface(SBI)providingforcommunicationandaccesstoexposedfunctionalities.

Thedeveloperofanapplicationtiershouldannotateitscodewithrequiredqualitativeandquantitative

characteristicsaccordingtothecontextmodel.Annotationscanbeincludedwithinthesourcecodeand

beproperly translatedbeforebuilding theexecutable,aswellasexternallyaccompany theexecutable

andbeproperlytranslatedbyothercomponentsofthearchitectureduringexecutable’splacementand

runtime.

AnindicativeHDAisdepictedinFigure1(a)thatcorrespondstoagraphcontainingasetoftiersalongwith

asetoffunctionsimplementedintheformofVirtualFunctions(VFs).ItshouldbenotedthatinARCADIA

weare adopting the termVirtual Functions (VFs) insteadof the termVirtualNetworking Function (VNF)

thatisdenotedinETSINetworkFunctionVirtualization(NFV)[6]sincewedonotonlyrefertonetworking

functions but to generic functions. Each element in the graph has to be accompanied with a set of

quantitative characteristics (e.g. set of metrics that can be monitored) and constraints (e.g. resource

capacity constraints, dependencies). In Figure 1(b) an application tier (T4) of the example is shown to

horizontally scalewhile the chain reconfigures itself by expanding and reforming, adding aswell a Load

Balancercomponentasnowrequired.

Figure1-(a)HDAIndicativeBreakdown,(b)HDAhorizontalscaling.

14/32

From an upper view, the lifecycle of an HDA starts from the development phase, followed by the

deployment phase and operation phase and ends with its termination. Each phase requires several

functional components of the architecture towork together to provide for and build an HDA, deploy it

assigningresourcesfromaninfrastructure,runitwhilemeetingobjectives-developerwiseand/orservice

provider wise- at all times and assure proper release of resources when terminates its operation.

Deployment, Operation and Termination are supported by the Smart Controller as the intermediate

between theapplicationsand the infrastructure,whiledevelopment is supportedby several repositories

providingeasyaccesstoreusablecomponentsandthedefinedcontextmodelprovidingaccesstothesetof

annotationsanddescriptions.

Takingunderconsiderationalltheaboveitistimetodefinethe8functionalcharacteristicsofanARCADIA

Nativeapplication.AnyARCADIANativeapplicationshould:

i. exposeitsconfigurationparametersalongwiththeirmetadata(e.g.whattheacceptablevalues?,can

theparameterchangeduringtheexecution?);

j. exposechainableinterfaceswhichwillbeusedbyothernativeapplicationsinordertocreateaservice

graph;

k. exposerequiredinterfaceswhichwillbealsousedduringthecreationofaservicegraph;

l. exposequantitativemetricsregardingtheQoSofthenativeapplication;

m. encapsulatea lifecycle-managementprogrammability layerwhichwillbeusedduring theplacement

ofoneservicegraphintheinfrastructuralresources;

n. bestatelessinordertobehorizontallyscalablebydesign;

o. bereactivetoruntimemodificationofofferedresourcesinordertobeverticallyscalablebydesign;

p. beagnostictophysicalstorage,networkandgeneralpurposeresources.

The analysis of these principles super-exceed the scope of the current deliverable. The reader should

consultD4.2[4]wherethesecharacteristicsareanalysed.Towardsthiscontext,theroleoftheannotation

frameworkisextremelyconcrete.Theannotationswillhandle:

• the automatic extraction and setting of configuration parameters according to the runtime

characteristicsofanativeapplication

• theautomaticregistrationoftheBItocentralregistry

• therun-timeselectionandchainingofapplicationsbasedontheBIcategory

• thebasiclifecyclemanagementi.e.(Deploy,Start,Stop,Undeploy)

• theautomaticinteractionwiththeARCADIAVFsthatareresponsibleforscaling

15/32

2.2 WhyanAnnotationFramework?Modern programming languages (such as Java and C#) offer an extremely useful mechanism named

‘annotations’thatcanbeexploitedforseveralpurposes.Annotationsareaformofmetadatathatprovide

dataaboutaprogramthatisnotpartoftheprogramitself. Inotherwords,aspecificsetofdesign-time

metadatacanbeusedatthesource-codelevelwhichwilldrivethenormativeschemacreation.Asalready

stated in D2.3 [2], from the software engineering perspective, annotations are practically a special

interface.Suchaninterfacemaybeaccompaniedbyseveralconstraintssuchasthepartsofthecodethat

canbeannotated(itiscalled@TargetinJava),thepartsofthecodethatwillprocesstheannotationetc.

AnindicativeannotationsdeclarationusingJavaispresentedinTable2-1.

Table2-1:Indicativedeclarationofanannotationtype

@Target({ElementType.METHOD})

@Retention(RetentionPolicy.RUNTIME)

@Inherited

@Documented

public@interfaceArcadiaService{

StringcontrollerURI()default"htttp://controller.arcadia.eu";

}

According to thisdeclaration,only Javamethodscanbeannotatedwith the@ArcadiaServiceannotation

(@Target({ElementType.METHOD})).Furthermore, thecompilationprocedurewill ignore theannotation;

yetthecompilerwillkeeptheannotationatthebinarylevelsincetheitwillbeprocessedduringruntime

(@Retention(RetentionPolicy.RUNTIME)). Furthermore, if the annotation method is overridden, the

annotationwill be automatically propagated to the overriddenmethod. In addition, annotationmay be

accompaniedbypropertiesthatcanbesetduringdeclaration. Intheaforementionedcase,theproperty

‘controllerURI’isusedtodenotetheURIofthehypotheticalARCADIASmartController.

Annotations can be used in multiple ways. Each framework selects one handling technique in order to

process annotations. In general, there are three strategies for annotations’ handling. More specifically

thesestrategiesinclude:

a. SourceGenerationStrategy:Thisannotationprocessingoptionworksbyreadingthesourcecode

and generating new source code ormodifying existing source code, and non-source code (XML,

documentation,etc.).Thegeneratorstypicallyrelyoncontainerorotherprogrammingconvention

16/32

andtheyworkwithanyretentionpolicy.Indicativeframeworksthatbelongtothiscategoryarethe

AnnotationProcessingTool3(APT),XDoclet4etc.

b. Bytecode Transformation Strategy: These annotation handlers parse the class files with

Annotationsandemitmodifiedclassesandnewlygeneratedclasses.Theycanalsogeneratenon-

class artifacts (like XML configuration files). Bytecode transformers can be run offline (compile

time),atload-time,ordynamicallyatrun-time(usingJVMTI5API).Theyworkwithclassorruntime

retention policy. Indicative bytecode transformer examples include AspectJ6, Spring, Hibernate,

CGLib7,etc.

c. Runtime Reflection Strategy: This option uses Reflection API to programmatically inspect the

objects at runtime. It typically relies on the container or other programming convention and

requiresruntimeretentionpolicy.ThemostprominenttestingframeworkslikeJUnit8andTestNG9

useruntimereflectionforprocessingtheannotations.

Fromthethreestrategiesthatarepresentedabove, thefirstonewillnotbeutilizedatall.However, the

secondandthethirdwillbeused.Morespecifically,the‘bytecodetransformationstrategy’willbeusedin

order to automate the procedure of normative schema generation regarding the facets ofmetadata,

requirements and configuration. To this end, specific type of annotations thatwill be processed during

compilation will generate representative schema instances which are in line with the ARCADIA Context

Model (see Deliverable D2.2 [1]). Finally, the ‘runtime reflection strategy’ will be utilized in order to

dynamicallyimplementspecificbehaviorsthatrelatetoprogramminginterfacebinding,measurementof

performancemetricsandgovernance.

ARCADIAmakesuseofJAVA’sextensibilitymechanismsnamely;“JSR-175:AMetadataFacilityfortheJava

Programming Language”10 and “JSR-269:Pluggable Annotation Processing API”11 to provide a set of

annotationsthatwillbedescribedbelowinordertoofferseveralfunctionalities.

3http://docs.oracle.com/javase/7/docs/technotes/guides/apt4http://xdoclet.sourceforge.net/xdoclet/index.html5http://docs.oracle.com/javase/7/docs/platform/jvmti/jvmti.html6https://eclipse.org/aspectj7https://github.com/cglib/cglib8http://junit.org9http://testng.org/doc/index.html10https://jcp.org/en/jsr/detail?id=17511https://jcp.org/en/jsr/detail?id=269

17/32

3 ARCADIAAnnotationsCurrently,thereare14annotationsthataredefined,whichservealsoafunctionalpurpose.Anoverviewof

theseannotations ispresentedonFigure212.Theannotationsare functionallygrouped in fivecategories

accordingtothenatureofthebusinesslogicthatisboundtotheusageoftheannotation.Thesecategories

include component management, configuration management, management of performance metrics,

managementoflifecycleandmanagementofdependencies.

Figure2-OverviewofARCADIAAnnotations

Inthenextsectionswewillelaborateeachgroupseparately.

3.1 ComponentManagementThefirstannotationthatadevelopercanuseisthe@ArcadiaComponentannotation.ThedefinitionoftheannotationisdepictedonFigure3.Asitisdepicted(fromtheElementType.Type)thespecificannotationisaclass-level annotation i.e. it can decorate any Java class. Therefore, any class that is annotated ascomponent will be handled. The handling that is bound to the annotation refers to the automaticgeneration of the formal component artefact and its registration to the ARCADIA Repository. More

12https://github.com/ubitech/arcadia-framework/tree/master/annotation-libs/src/main/java/eu/arcadia/annotations

18/32

specifically,asalreadyanalysedinD2.3[2]thecreationofanHDAapplicationinvolvesthecompositionofseveral components that are already registered in a repository. The meta-model of the “chainable”componentisdepictedonFigure4.

Figure3-ArcadiaComponentAnnotation

19/32

Figure4-SerializationModelforaspecificcomponent

AsitisdepictedinFigure4theformalmetamodelisexpressiveenoughtocapturethe“chainable”profileofacomponent.Howeveras itwillbeshownbelow,thevariouselementsthatcomprisethemodel (e.g.ExposedChainableEndpoints)areindicatethroughdifferentannotations.

3.2 ConfigurationManagementAnother annotation that a developer canuse is the@ArcadiaConfigurationParameter. Thedefinitionofthe annotation is depicted on Figure 5. As it is shown, this annotation is also a class-level annotation.ThroughthisannotationadevelopercandeclareaconfigurationparameterwhichwillautomaticallyenrichthecomponentmodelthatisregisteredintheARCADIArepository.Theannotationsupports5argumentsi.e. ‘name’, ‘description’, ‘parameterType’, ‘defaultvalue’ and ‘mutableafterstartup’. ‘Name’ is used todeclare themethod-name that exposes a configuration parameter. It should be clarified that using theprinciple of reflection themethods setName andgetName are automatically exposed aswewill explainlater. The ‘description’ provides a detailed explanation of the configuration parameter. The‘parameterType’ denotes if a parameter is single-value ormulti-value. Finally,while the ‘defaultvalue’ isself-explanatory the ‘mutableafterstartup’ denotes whether or not a configuration parameter can bealteredafterthecomponentinitialization.

20/32

Figure5–ConfigurationParameterAnnotation

The enrichment of the component model is not the only business logic that is bound to the specificannotation.ThemostcrucialaspectistheautomaticgenerationofathinRESTlayerthatisresponsibletoexpose the configuration parameters offering a ‘proxy’ for both setters and getters. This REST layer isconsumedonlybytheARCADIASmartController.Asdiscussed inD3.1 [3]anyservicegraph is relatedtotwotypesofpolicies.Thefirstpolicyisthedeploymentpolicyandthesecondistheruntimepolicy.Partofthe runtime policy is the reconfiguration of the component based on the monitoring streams that aregenerated.Aserviceprovidermaytriggerthechangeofamutableconfigurationparameterduringruntimein the frameof apolicyexecution. This changewill beperformedbasedon the interactionof theSmartControllerwiththeaforementionedRESTlayer.

3.3 Component’sMetricsThe third family of annotations that are provided to the developers are the@ArcadiaMetric and the@ArcadiaMetrics.BothoftheseannotationsaredepictedonFigure6andFigure7,respectively.

21/32

Figure6–ArcadiaMetricAnnotation

Figure7–ArcadiaMetricsAnnotation

Since the@ArcadiaMetrics annotation is just an easy way to declare multiple@ArcadiaMetric we willemphasize our analysis in the latter. @ArcadiaMetric is a class-level annotation and is used to declaremethodsthatreturnspecificuser-definedmeasurements.Anindicativeusageoftheannotationwouldbethefollowing:

@ArcadiaMetric(name="averageProcessingTime",description = "URL hashing algorithmperformance",unitofmeasurement = "msec",valuetype = ValueType.SingleValue,maxvalue ="6000",minvalue="1",higherisbetter=false)

22/32

As it [email protected] ‘name’denotesthemethodthat implements the actual stream extraction. Therefore, the indicative "averageProcessingTime" infersthatthereisagetAverageProcessingTime()methodthatcanbeinvoked.The‘unitofmeasurement’providestheappropriateunitthatcanbeusedduringquantificationwhiletheminandmaxdenotetherespectivebounds. TheBoolean flag ‘higherisbetter’ indicatewhether the increaseof ameasurement is consideredpositiveornot.

Thebusiness logic that isbound to thespecificannotation is theautomaticgenerationofaRESTservicethat exposes the monitoring stream based on the requests of a Smart Controller. This is completelyanalogous to the business logic that has been developed for the@ArcadiaConfiguration; yet there is asignificant difference. In the current case only a getter ismeaningful since the runtime policies that areenforcedrequirethehandlingofmultipleparallelstreamsthatrefertoeitherVM-metricsofuser-definedmetrics.ThestreamsthatrefertotheVM-metricsareembeddedintheVMwhilethestreamsthatrefertothe user-defined metrics are automatically generated through the runtime interpretation of theannotation.

3.4 LifecycleManagementAcrucialaspect regardingtheARCADIAcomponents is theapplication lifecyclemanagement (hereinafterALM).TheALMrefers to theentireservicegraphasalongas tocomponents thatparticipate inaservicegraph.Sinceaservicegraphisadirectedacyclicgraphthecomponentsentailseveraldependenciesamongthem.Therefore, thedeploymentofonecomponent followsa strictbootstrappingprotocolaccording towhich the component has to be firstly initialized (i.e. its execution environment is available), then itsdependencieshavetoberesolvedandfinallythemainexecutioncontextshouldstart.

Figure8–LifecycleInitializeAnnotation

The implementation of the bootstrapping protocol is under the responsibility of the Smart Controller.However, the Smart Controller does not have the knowledge of the secrete internal states of thecomponent. Therefore, specific annotations are required to denote the context initialization and thestart/stop. These annotations are the @LifecycleInitialize (Figure 8), @LifecycleStart (Figure 9) and@LifecycleStop(Figure10),respectively.

23/32

Figure9–LifecycleStartAnnotation

Figure10–LifecycleStopAnnotation

As itcanbenoticed, theseannotations,contrary totheonesthatwehaveexamineduptonow,arenotclass-level but method-level. This is denoted by the ElementType.METHOD tag. This is deliberate sincetheseannotationsdecorateexistingmethods in thecodethatwillbe invokedwhentheSmartControllerdictates. Inorderfortheinvocationtobeperformedapass-throughRestcallwillbeperformedfromtheController to the component. This is completely analogous to what is happening in the case of theconfigurationmanagementandthecaseofexportofthemonitoringstreams.

3.5 DependencyManagementThe final set of annotations that can be used relate to the exposure and the usage of component’sinterfaces.AsalreadyanalysedthoroughlyinD2.2[1]eachcomponentmayexposeoneormoreinterfacesafter its initialization.Ontheotherhand,thesamecomponentmayrequireoneormore interfaces fromthird-party components before the actual initialization. Handling both the advertisement of an interfaceandthechainingrequirementisperformedthroughtwodistinctannotationsi.e.the@DependencyExportandthe@DependencyResolutionHandler.

24/32

Figure11–DependencyExportAnnotation

@DependencyExport(class-level annotation) publishes to a high-available microservice repository thepublished interfacewhile the@ResolutionHandlerdecoratesamethodwhichwillhandle theoutputofalookupservicethataimstoidentifyarequiredservice.

Figure12–DependencyResolutionHandlerAnnotation

ItshouldbenotedthatinAnnexI,acompletelyannotatedcomponentisappended.

25/32

4 UsageofAnnotationsARCADIA is designed to help developers create and deploy applications quicker andmore efficiently. Itautomates many tasks such as code and annotation validation, application deployment and applicationmonitoring. The development of components will be performed using the ARCADIA web-based IDEenvironment. Through this environment, developers can use the aforementioned annotations that arevalidatedbythesmartcontrollerandareautomaticallyinterpretedtocomponents.Thisstandstrueonlyinthecaseofnativeapplications.

4.1 ARCADIAweb-basedIDEenvironmentAs it isexplained inD4.2[4]the IDEenvironmentreliesonastate-of-the-artweb-basedIDEcalledEclipseChe13whichgivesthepossibilitytothedeveloperstodevelopcomponents inacollaborativeway.EclipseChe isageneral-purposeweb-based IDE.Che isbasedonDocker14,GWT15,Orion16andRESTfulAPIsandoffersboth client and server side capabilities.The client-sideofChe isbasedon theOrioneditor, and itoffersmostofthefeaturesexpectedfromaclassicIDEsuchasautomaticcodecompletion,errormarking,JAVA“intelligence”anddocumentation.Ontheotherhand,theserversideisresponsibleformanagingthecode repository, compilingandexecutingprogramsandmanaging runtimes. Througha specificARCADIApluginthatisbeingdevelopedtheinteractionoftheIDEwiththeSmartControllerwillbeautomated.

The primary task of the ARCADIA IDE plugin is to assist developers during component development.Throughtheplug-in,developerscanviewallavailableARCADIAannotations,includingsomeJavadoc-baseddocumentation, authenticatewith theARCADIA platform and trigger component validation, through theARCADIAserver-sideplug-in.

Specifically, when a developer starts writing an ARCADIA annotation, the plug-in offers auto-completesuggestionswheredevelopers can just choosewhich annotation theywant to use. In addition, they canread the specifications of each annotation, like the required fields, naming conventions and examples.Moreover, if theychoose touseoneof theprovidedcomponent templates, theplug-inwillmanageanyARCADIA requirement like maven dependencies. Using the web-based IDE, developers can developcomponentsthatadheretotheARCADIAcomponentmetamodel.Thiscompliancyisachievedthroughtheusage of specific annotations that allow developers to declare components, register configurationparameters,definechainableendpointsetc.

Theusageofannotationsisperformedinaseamlesswaythroughthedevelopmentenvironment.Figure13depicts the development of an actual component. As it is depicted the developer is using severalannotations such as@ArcadiaComponent,@ArcadiaMetric,@ArcadiaExport etc. The definition of theseannotations during development is assisted by the IDE per se while the functional usage of theseannotationstakeplaceafterthesubmissionoftheexecutabletotheSmartController.

13https://eclipse.org/che/14https://www.docker.com/15http://www.gwtproject.org/16https://orionhub.org/

26/32

Figure13–DevelopmentofARCADIAcomponentthroughweb-basedIDE

4.2 ValidationofAnnotations&GenerationofThinlayer

AfterthesubmissionofthecomponenttotheSmartController,thesystemperformsasetofvalidationsinordertocheckthelogicalvalidityoftheprovidedannotations.Itshouldbenotedthatthestructuralvalidityof the annotations is not checked since if the project compiles correctly structural validity is assured.However,thelogicalvalidityreferstoasetofaspectssuchastheuniquenessofthecomponentname,theexistenceoftherealmethod-hooksthatcorrespondtothevariousgetters(e.g.getMetricX),theavoidanceof conflicting versions, the existenceof chainable endpoints etc. All these are a small part of the logicalvalidationwhichisperformedusingBytecodeintrospectiontechniques.

The maven module that performs the actual introspection is called “annotationinterpreter”. Figure 14depictstheexactlocationintheprojects’sourcecoderepositorywherethismoduleexists.Thesourcecoderepositoryislocatedatthefollowingurl:https://github.com/ubitech/arcadia-framework

https://github.com/ubitech/arcadia-framework

27/32

Figure14–MavenmodulethatperformstheAnnotationintrospection

Whenthecomponentpassesthevalidationphase,theexecutablealongallmetadatathataccompanytheexecutablearestoredinastructuredformatintheSmartController’spersistencyengine.Aspecificparserthat is embedded in the annotationinterpreter undertakes the task to transform the arguments of theannotations (e.g. ArcadiaComponent(name=”xxx”) ) to a serialized format that adheres to the ARCADIAContextModel[2].

The next step after the validation is the creation of the thin REST layer which is attached to eachcomponent. The thin REST layer is developed in the frameof the ‘agent’mavenmodule17. This agent isinitializedbyaconfigurationfilethat isgeneratedautomaticallyafterthevalid introspection.ThesnippetbelowprovidessuchconfigurationfortherealservicethatisprovidedinAnnexI.

{

"className": "eu.arcadia.annotationinterpreter.sample.URLShortener",

"CNID": "d1e39865-02be-4b57-9896-6cde075d8f79",

"lifecycleInitMethod": "init",

"lifecycleStartMethod": "start",

"lifecycleStopMethod": "stop",

"dependencyResolutionHandlers": {},

"dependencyBindingHandlers": {

"MONGODB_CONNECTION": "bindMongoDB"

},

"metrics": [

"hashedURLs",

"averageProcessingTime"

17https://github.com/ubitech/arcadia-framework/tree/master/agent

28/32

],

"configurationParameters": [

"hashLength"

]

}

Whenthecomponentisactivatedtheagentbootstraps.UponbootstrappingaRESTinterfaceisexposedto

theSmartController.SuchaRESTinterfacefortheserviceisprovidedbelow.

/conf/set/hashLength [POST]

{

"value": "7"

}

/conf/get/hashLength [GET]

{

"value": "7"

}

Metrics:

/metric/get/hashedURLs [GET]

{

"value": "1"

}

/metric/get/averageProcessingTime [GET]

{

"value": "1"

}

29/32

5 ConclusionsThepurposeof thisdeliverablewas toelaborateon thecode-levelannotations thathavebeendesigned

andonthebusiness logicthat isboundtotheseannotations.Annotationspersearefeaturesofmodern

programminglanguagesthatallowdevelopersto‘decorate’theirprograms.Thisdecorationprovidestothe

developedprogramspecific functionalitywhich iseitherdesign-time (i.e.duringcompilation)or run-time

(i.e.duringexecution).To thisend,ARCADIAmadeuseof JAVA’sextensibilitymechanismsnamely; “JSR-

175: A Metadata Facility for the Java Programming Language” and “JSR-269:Pluggable Annotation

ProcessingAPI”toprovideasetofannotationsthatacceleratesthedevelopmentofHDAapplications.

ARCADIAannotationsare functionally grouped in five categoriesaccording to thenatureof thebusiness

logic that is bound to the usage of the annotation. These categories include component management,

configuration management, management of performance metrics, management of lifecycle, and

managementofdependencies.Foreachofthesecategoriestheexactbusinesslogicisdiscussed.

Regardingthecomponentmanagement,aproperannotationundertakesthetasktocreatetheappropriate

artefactandstoreitintheARCADIArepositoryinordertobeusedlateronduringthecreationofaservice

graph. Regarding, the configurationmanagement aspects, the annotations are used in order to create a

fullyfunctionalRESTthin-layeron-topofthecomponentthatundertakethetaskofgettingorsettingthe

configuration parameters. It should be clarified that getting is only meaningful in case of mutable

parameters. As farasperformancemetricsareconcerned,aproperannotation is responsible toexpose

developer-defined measurements per each metric. These measurements are propagated to the Smart

Controllerthatisresponsibleforthepolicyenforcement.

Finally,regardinglifecyclemanagement,ARCADIAannotationsimplementpass-throughfunctionsthatare

requiredbytheSmartControllerintheframeofaservicegraphdeployment.Aservicegraphdeployment

entailsaspecificbootsequenceprotocolthatrequiresuniforminteractionwithallpartsofthegraph.An

analogous REST thin-layer that is auto-generated provides the required uniform interaction. The same

stands true regarding the exposure and the binding of the interfaces that a component may perform.

ARCADIAannotationscanbeusedinanyIDEenvironment.However,intheframeoftheprojectaspecific

web-basedIDEwillbeprovidedthatwillperformseveraltypesofvalidationontheARCADIAcomponents.

30/32

References[1] Arcadiaproject,D2.2-ARCADIAContextModel,AvailableOnline:http://www.arcadia-

framework.eu/wp/documentation/deliverables/

[2] Arcadiaproject,D2.3-ARCADIAArchitecture,AvailableOnline:http://www.arcadia-framework.eu/wp/documentation/deliverables/

[3] Arcadiaproject,D3.1-SmartControllerReferenceImplementation

[4] Arcadiaproject,D4.2-DescriptionoftheApplications’LifecycleManagementSupport,AvailableOnline:http://www.arcadia-framework.eu/wp/documentation/deliverables/

[5] M.Dalmau,P.Roose,S.Laplace,“ContextAwareAdaptableApplications-Aglobalapproach,”IJCSIInternationalJournalofComputerScienceIssues,Vol.1,2009

[6] ETSI,NetworkFunctionVirtualization,Online:http://www.etsi.org/technologies-clusters/technologies/nfv

http://www.arcadia-framework.eu/wp/documentation/deliverables/





http://www.etsi.org/technologies-clusters/technologies/nfv

http://www.etsi.org/technologies-clusters/technologies/nfv

31/32

AnnexI–SampleAnnotatedComponentpackage eu.arcadia.sample;

import eu.arcadia.annotations.*;

import org.springframework.boot.SpringApplication;

@ArcadiaComponent(componentname = "URL Shortener",componentversion = "1.1.0",componentdescription = "Make a long URL short, easy to remember and to share.",tags={"url-shortener","server"})

@ArcadiaMetric(name="hashedURLs",description = "Total number of shrinked URLs",unitofmeasurement = "integer",valuetype = ValueType.SingleValue,maxvalue = "2147483648",minvalue = "0",higherisbetter = false)

@ArcadiaMetric(name="averageProcessingTime",description = "URL hashing algorithm performance",unitofmeasurement = "msec",valuetype = ValueType.SingleValue,maxvalue = "6000",minvalue = "1",higherisbetter = false)

@DependencyExport(CEPCID = "URLSHORTENER_REST_API",allowsMultipleTenants = true)

@ArcadiaConfigurationParameter(name = "hashLength",description = "Defines the length of the hash representing the shrinked URL",parametertype = ParameterType.SingleValue,defaultvalue = "7", mutableafterstartup = false)

public class URLShortener {

/*

ArcadiaConfigurationParameter setter/getter

*/

public static void setHashLength(String length){

//application logic

System.setProperty("URLShortener.hashLength",length);

}

public static String getHashLength(){

//application logic

return System.getProperty("URLShortener.hashLength");

}

/*

ArcadiaMetrics (getters only)

*/

public static String getHashedURLs(){

//application logic

return "1";

}

public static String getAverageProcessingTime(){

//application logic

return "1";

}

/*

32/32

Component Lifecycle Management

*/

@LifecycleInitialize

public static void init(){

System.setProperty("server.port",Application.defaultPort.toString());

System.setProperty("URLShortener.hashLength",Application.defaultHashLength.toString());

}

@LifecycleStart

public static void start(){

new SpringApplication(Application.class).run();

}

@LifecycleStop

public static void stop(){

}

/*

DependencyExport-related methods (for URLSHORTENER_REST_API)

*/

public static String getUri(){

return Application.defaultUri;

}

public static String getPort(){

return Application.defaultPort.toString();

}

/*

Handle the bidning of the required MongoDB component (set application-specific properties etc.)

*/

@DependencyBindingHandler(CEPCID = "MONGODB_CONNECTION")

public void bindMongoDB(String ecepid, String json){

}

}

Description of the Supported Metadata Annotations

Technology

Transcript of Description of the Supported Metadata Annotations