Java annotations export


#1

Hello,
I need to export with Doc Composer a document from a class diagram.
My classes contain operations with Java Annotation elements.
Is it possible to create an Xml template in order to generate the document with the annotations?
I tried with the following code but it doesn’t work:

<HasValueChecker property="javaDetail">
                    <ForEach property="javaDetail">
                        <TableRow>
                            <TableCell>
                                <Text>Java Annotations</Text>
                            </TableCell>
                            <TableCell>
                                <Property property="name"/>
                                <HasValueChecker property="type">
                                    <Text> : </Text>
                                    <Property property="type"/>
                                </HasValueChecker>
                            </TableCell>
                        </TableRow>
                    </ForEach>
                </HasValueChecker>

Thanks in advance,
BR
Sabrina


#2

First of all a small (yet important) disclaimer: please keep in mind that I don’t have much experience with the doc. composer, so I can’t rule out the possibility that I might be overlooking something here.

Still, I’m giving it my best though :slight_smile:

Solely basing myself on the doc composer online template manual I think this is indeed possible. I think you used the wrong property: you used javaDetail but shouldn’t that be JavaAnnotation or maybe JavaAnnotationProperty?

See this link.

Hope this can give you some ideas.


#3

Thanks for your answer,
but I tried also javaAnnotationProperty and javaAnnotation properties, the behavior is the same.


#4

In the mean time I gave myself a crash course on Doc composer and I have to say that this is definitely an impressive feature. I now also understand why you used javaDetail and can confirm that this is correct.

But there are some caveats to address.

For example… To rule out mishaps I started to concentrate on examples from the documentation (doc composer writers guide), in specific a very elementary detail: the description.

Check this out:

	<ValueChecker property="description">
		<Text>A description was found!</Text>
	</ValueChecker>

If you test this routine you’ll discover something very interesting: it only evaluates to true if no description was found. This is a bit confusing at first (at least it was for me), especially if you consider that ‘value’ is an optional property. But it makes sense: by not defining the ‘value’ property it won’t have an actual value (empty) so… you’re checking for a property with an empty value.

And I think that this aspect could be related to your results above (note: this is only a wild theory of mine so far). Consider this:

	<HasValueChecker property="javaDetail" modelType="JavaClassCodeDetail">
		<Text>An annotation was found!</Text>
		<ValueChecker property="javaDetail" operator="not equals" value="">
			<Property property="javaDetail" />
		</ValueChecker>
	</HasValueChecker>

The result of this is “unnamed”. So there definitely is some kind of element to work with here!

If I then study JavaClassCodeDetail some more I find the ‘annotation’ property, and that’s the thing we’re after here!

So right now I think the main problem is that ‘annotations’ is a property within the ‘javaDetail’ property. And to make this worse: the data we’re after is within the annotations (that is the actual JavaAnnotation class).

(in case you’re wondering about my current (maybe somewhat chaotic) writing style: I’m actually thinking and experimenting while writing all this).

Anyway, this is also where I’m currently stuck:

	<HasValueChecker property="javaDetail" modelType="JavaClassCodeDetail">
		<Text>An annotation was found:</Text>
		<Property property="javaDetail"/>
		<ParagraphBreak/>
		<ValueChecker property="javaDetail" operator="not equals" value="">
			<Text>javaDetail has an actual value!</Text>
			<ForEach property="javaDetail">
				<Property property="name"/>
				<Property property="annotations"/>
			</ForEach>
			<IterationBlock modelType="JavaClassCodeDetail">
				<Property property="name"/>
				<Property property="annotations"/>
			</IterationBlock>
		</ValueChecker>
	</HasValueChecker>

I’m probably overlooking something but can’t put my finger on it just yet.

Hopefully this might give you some more ideas, I’m going to continue this tomorrow.


#5

The problem is that by the javaDetail property is found but its properties no!
I have no more ideas about to resolve the problem.
Only javaDetail has this behavior; other properties like Template Parameters, Tagged Values work fine.
I need to retrieve operation annotations for each class but I don’t know if there is another solution.
Thank for your help.
BR
Sabrina


#6

Quick reply because I noticed you just replied :wink:

Don’t give up just yet because I found something! Something briefly (“hardly”) mentioned in the documentation and I think this is the key to the Annotations: <ModelElementProperty>.

I was studying the Element:Class/Details template when it suddenly hit me:

			<HasValueChecker property="ormDetail">
				<ModelElementProperty property="ormDetail">
					<HasValueChecker property="tableModel">

See?

I think this is our way in. I’m going to set up a testcase soon (got a few obligations I need to attend to first) and I’ll keep you posted.

btw: really good question by the way! I fully agree: this could have been documented a little bit better. But maybe I can help them with that (if my plan works then I’m definitely going to write & send in some update suggestions to the VP team).


#7

What do you know? I was right!

The good news is that I managed to gain access to the annotation names. The bad news is that I’m still struggling a bit with the elements, but that’s merely a matter of time and the right property.

Here’s my code so far:

	<HasValueChecker property="javaDetail" modelType="JavaClassCodeDetail">
		<Text style="Heading 1">Java details found!</Text>
		<ParagraphBreak/>
		<Property property="javaDetail"/>
		<ParagraphBreak/>
		<ModelElementProperty property="javaDetail">
			<HasValueChecker property="annotations" modelType="JavaAnnotation">
				<Text style="@heading+">Annotation(s) found!</Text>
				<ParagraphBreak/>
				<Property property="annotations"/>
				<ParagraphBreak/>
				<ForEach property="annotations">
					<Text style="@heading+">Found annotation: </Text>
					<Property property="name"/>
					<ParagraphBreak/>
					<Property property="description"/>
				</ForEach>
			</HasValueChecker>
		</ModelElementProperty>
	</HasValueChecker>
</ElementBaseInitiationBlock>

You’ll notice that the template lists all the names, but ‘description’ doesn’t do anything useful. However… I now realize that I’m making a mistake here: the elements / properties isn’t a static description (aka String) but it’s another list of elements!

And I found it: properties.

Here’s an expansion of my last ForEach block:

				<ForEach property="annotations">
					<ParagraphBreak/>
					<Text style="@heading+">Found annotation: </Text>
					<Property property="name"/>
					<HasValueChecker property="properties">
						<ParagraphBreak/>
						<Text style="@heading+">Properties found : </Text>
						<Property property="properties"/>
					</HasValueChecker>
				</ForEach>

Those properties could get tricky because you’re also allowed to add models (Model elements) in there. But as long as you leave those to text properties only it shouldn’t be too much of a problem.

I hope this can help! :smile:


#8

I got it!

Now, the formatting may not be what you’re looking for but you can easily change that if you want, so here’s what it looks like:

image

… for these Java annotations:

Not too bad I think :slight_smile:

And here’s my final template code:

<?xml version="1.0" encoding="UTF-8"?>
<ElementBaseInitiationBlock>

	<Text style="@heading+">Overview of assigned Java annotations</Text>
	<ParagraphBreak/>

	<HasValueChecker property="javaDetail" modelType="JavaClassCodeDetail">
		<ModelElementProperty property="javaDetail">
			<HasValueChecker property="annotations" modelType="JavaAnnotation">
				<Text style="@heading+">Assigned annotations</Text>
				<ParagraphBreak/>
				<ForEach property="annotations">
					<Text>Name: @</Text>
					<Property property="name"/>
					<ParagraphBreak/>
					<HasValueChecker property="properties">
						<Text style="@heading+">List of elements</Text>
						<TableBlock tableStyle="Summaries" tableWidth="80%" repeatTableHeader="true">
							<TableRow>
								<TableCell>
									<Text>Name</Text>
								</TableCell>
								<TableCell>
									<Text>Value</Text>
								</TableCell>
							</TableRow>
							<ForEach property="properties">
								<TableRow>
									<TableCell>
										<Property property="name"/>
									</TableCell>
									<TableCell>
										<Property property="value"/>
									</TableCell>
								</TableRow>
							</ForEach>
						</TableBlock>
						<ParagraphBreak/>
					</HasValueChecker>
				</ForEach>
			</HasValueChecker>
		</ModelElementProperty>
	</HasValueChecker>
</ElementBaseInitiationBlock>

Keep one very important aspect in mind here: Visual Paradigm also allows you to assign models as annotation values. If you do so you basically get a text (description) and an icon. Being a Java programmer myself I can’t imagine how you’d set up an icon in a Java annotation so I skipped that part; only the name (‘text’) gets displayed here.

I hope this is useful for you, I sure learned quite a few new tricks here! :sunglasses:


#9

Sorry for a double post but… I was re-reading my above message and when looking at the template output again I think it looks a bit sloppy, surely I can do better than that? Especially now that I got a good taste of the Doc Composor. I definitely intend to keep this template, and who knows if it might become useful for me in the future.

So, uhm… “I did something” :slight_smile:

image

I hope you can agree that this looks much better than that mess in my previous post? As you can see I even discovered a way how you can use properties (such as the annotation name) in a header, how cool is that?

Anyway, figured I’d share this edit as well. Also because you intentionally started with the idea to use a table yourself so I figured that this might also be useful for you.

<?xml version="1.0" encoding="UTF-8"?>
<ElementBaseInitiationBlock>

	<Text style="@heading+">Overview of Java annotations</Text>
	<ParagraphBreak/>

	<HasValueChecker property="javaDetail" modelType="JavaClassCodeDetail" flag="false">
		<Text>No annotations used in class </Text>
		<Property property="name"/>
		<Text>.</Text>
		<ParagraphBreak/>
	</HasValueChecker>

	<HasValueChecker property="javaDetail" modelType="JavaClassCodeDetail" flag="true">
		<Text style="@heading+">Class </Text>
		<Property style="@heading" property="name"/>
		<ParagraphBreak/>
		<ParagraphBreak/>
		<ModelElementProperty property="javaDetail">
			<HasValueChecker property="annotations" modelType="JavaAnnotation">
				<TableBlock tableStyle="Summaries" tableWidth="60%">
					<TableRow>
						<TableCell>
							<Text>Annotation</Text>
						</TableCell>
						<TableCell>
							<Text>Contains definitions?</Text>
						</TableCell>
					</TableRow>
					<ForEach property="annotations">
						<TableRow>
							<TableCell>
								<Text>@</Text>
								<Property property="name"/>
							</TableCell>
							<TableCell>
								<HasValueChecker property="properties" flag="true">
									<Text>Yes</Text>
								</HasValueChecker>
								<HasValueChecker property="properties" flag="false">
									<Text>No</Text>
								</HasValueChecker>
							</TableCell>
						</TableRow>
					</ForEach>
				</TableBlock>
				<ParagraphBreak/>
				<Text style="@heading">List of annotation definitions (optional)</Text>
				<ParagraphBreak/>
				<ForEach property="annotations">
					<Text style="@heading+">@</Text>
					<Property style="@heading" property="name"/>
					<HasValueChecker property="properties" flag="false">
						<ParagraphBreak/>
					</HasValueChecker>
					<HasValueChecker property="properties" flag="true">
						<ParagraphBreak/>
							<TableBlock tableStyle="Summaries" tableWidth="80%">
								<TableRow>
									<TableCell>
										<Text>Name</Text>
									</TableCell>
									<TableCell>
										<Text>Value</Text>
									</TableCell>
								</TableRow>
								<ForEach property="properties">
									<TableRow>
										<TableCell>
											<Property property="name"/>
										</TableCell>
										<TableCell>
											<Property property="value"/>
										</TableCell>
									</TableRow>
								</ForEach>
							</TableBlock>
					</HasValueChecker>
				</ForEach>
			</HasValueChecker>
		</ModelElementProperty>
	</HasValueChecker>
</ElementBaseInitiationBlock>

#10

Good!
It works for class annotations but I still have the problem for operation annotations.
I need to retrieve the annotations for each operation of a class.


the property javaDetail is always false for the modelType JavaClassCodeDetail of the operation:

No annotations used in class

.


Perhaps I need to nest an iteration on another modelType. What do you think about it?
Thanks
BR
Sabrina


#11

Be sure that you check my last post (I wrote two), so this one.

Is it possible that you overlooked that one? Because I solved the problem with the operations in there, they get listed in a table after every annotation:

image

(so: the items like address, name and audio are actually annotation elements).

Unless of course you meant something else…


#12

I tried in my project your template (the correct post) and it works only for class annotations.
If you look in my picture you see that there are two “Java Annotations”; the annotations related to the operations are in a lower level so when I check javaDetail property on modelType JavaClassCodeDetail the result is false.
Instead, for class annotations it is true.
In any case I’ll try again this afternoon.
Thanks for your suggestions.
BR
Sabrina


#13

Now I see what you’re getting at. Yeah, that’s an obvious silly oversight on my end.

But I think I know how to handle this; we need to iterate through the whole lot. The class annotations, the class attributes to check those annotations and then finally the class operators and check those as well.

And because the annotation part will be basically the same we might even be able to use some recursion (re-using the template).

I’m also going to look into this, and I’ll keep you posted!


#14

Java annotations, take 2!

Sorry again for that oversight on my end. I was so focused on going through the annotation properties (class properties) that I totally forgot about the rest! :blush:

But better late than never, I now have a template which checks the class annotations and then those for the operations and attributes. And even though I’m still a bit unsure about the layout I think it turned out decent enough:

Some important details:

The headers will always show, even if no annotations were found:

image

I did this for consistency. The class annotations are merely a property and you could easily check that beforehand. But the attributes and operations need to be checked individually and you can’t apply programming logic while using a loop. That is: you can check the individual aspects, but not the entire collection.

So to keep the template persistent all headers are printed no matter what.

This was quite an educational experience I must say…

So here is the full template:

<?xml version="1.0" encoding="UTF-8"?>
<ElementBaseInitiationBlock>

	<Text style="@heading+">Overview of Java annotations</Text>
	<ParagraphBreak/>
	<Text style="@heading+">Class annotations</Text>
	<ParagraphBreak/>

	<HasValueChecker property="javaDetail">
		<ModelElementProperty property="javaDetail">
			<HasValueChecker property="annotations">
				<ParagraphBreak/>
				<ForEach property="annotations">
					<Text>@</Text>
					<Property property="name"/>
					<ParagraphBreak/>
					<HasValueChecker property="properties">
						<Text style="@heading+">Definitions:</Text>
						<TableBlock tableStyle="Summaries" tableWidth="80%">
							<TableRow>
								<TableCell>
									<Text>Name</Text>
								</TableCell>
								<TableCell>
									<Text>Value</Text>
								</TableCell>
							</TableRow>
								<ForEach property="properties">
									<TableRow>
										<TableCell>
											<Property property="name"/>		
										</TableCell>
										<TableCell>
											<Property property="value"/>		
										</TableCell>
									</TableRow>
								</ForEach>
						</TableBlock>
						<ParagraphBreak/>
					</HasValueChecker>
				</ForEach>
			</HasValueChecker>
		</ModelElementProperty>
	</HasValueChecker>

	<Text style="@heading+">Attribute annotations</Text>
	<ParagraphBreak />
	
	<HasChildElementChecker modelType="Attribute">
		<IterationBlock modelType="Attribute">
			<ConditionsChecker>
				<Conditions type="and">
					<HasValueChecker property="name"/>
					<ModelElementPropertyConditionChecker property="javaDetail">
						<HasValueChecker property="name"/>
					</ModelElementPropertyConditionChecker>
				</Conditions>
				<Property style="@heading+" property="name"/>
				<ParagraphBreak/>
				<ModelElementProperty property="javaDetail">
					<ForEach property="annotations">
						<Text>@</Text>
						<Property property="name"/>
						<ParagraphBreak/>
						<HasValueChecker property="properties">
							<Text style="@heading+">Definitions:</Text>
							<TableBlock tableStyle="Summaries" tableWidth="80%">
								<TableRow>
									<TableCell>
										<Text>Name</Text>
									</TableCell>
									<TableCell>
										<Text>Value</Text>
									</TableCell>
								</TableRow>
									<ForEach property="properties">
										<TableRow>
											<TableCell>
												<Property property="name"/>		
											</TableCell>
											<TableCell>
												<Property property="value"/>		
											</TableCell>
										</TableRow>
									</ForEach>
							</TableBlock>
							<ParagraphBreak/>
						</HasValueChecker>
					</ForEach>
				</ModelElementProperty>
			</ConditionsChecker>
		</IterationBlock>
	</HasChildElementChecker>

	<Text style="@heading">Operation annotations</Text>
	<ParagraphBreak />

	<HasChildElementChecker modelType="Operation">
		<IterationBlock modelType="Operation">
			<ConditionsChecker>
				<Conditions type="and">
					<HasValueChecker property="name"/>
					<ModelElementPropertyConditionChecker property="javaDetail">
						<HasValueChecker property="name"/>
					</ModelElementPropertyConditionChecker>
				</Conditions>
				<Property style="@heading+" property="name"/>
				<ParagraphBreak/>
				<ModelElementProperty property="javaDetail">
					<ForEach property="annotations">
						<Text>@</Text>
						<Property property="name"/>
						<ParagraphBreak/>
						<HasValueChecker property="properties">
							<Text style="@heading+">Definitions:</Text>
							<TableBlock tableStyle="Summaries" tableWidth="80%">
								<TableRow>
									<TableCell>
										<Text>Name</Text>
									</TableCell>
									<TableCell>
										<Text>Value</Text>
									</TableCell>
								</TableRow>
									<ForEach property="properties">
										<TableRow>
											<TableCell>
												<Property property="name"/>		
											</TableCell>
											<TableCell>
												<Property property="value"/>		
											</TableCell>
										</TableRow>
									</ForEach>
							</TableBlock>
							<ParagraphBreak/>
						</HasValueChecker>
					</ForEach>
				</ModelElementProperty>
			</ConditionsChecker>
		</IterationBlock>
	</HasChildElementChecker>
</ElementBaseInitiationBlock>

Hope this can be more useful than the previous versions :slight_smile: