Invalid Java package names

[rmkellogg]

Azure-Boards-Metadata-v3.0.zip

Using latest release the Java classes generated against Azure Boards includes prefix of "default.x" in generated package names in .java files. I think there is a missing check for reserved words against the package names generated.

Metadata sample file attached. I manually modified the .java files to work around.

Very helpful project.

[davidmoten]

Thanks, I'll have a look.

[davidmoten]

Can you show me the pom.xml fragment you are using to generate the classes? I believe you can set the generated package names in the plugin yourself to avoid the default behaviour. In the meantime I'll see what I can do about the default behaviour so that it does the right thing. Below is how the msgraph classes are generated. You'll see you can map a namespace to a package yourself there.

<plugin>
                <groupId>com.github.davidmoten</groupId>
                <artifactId>odata-client-maven-plugin</artifactId>
                <version>${project.parent.version}</version>
                <executions>
                    <execution>
                        <id>generate-msgraph-client</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <metadata>../odata-client-generator/src/main/odata/msgraph-metadata.xml</metadata>
                            <schemas>
                                <schema>
                                    <namespace>microsoft.graph</namespace>
                                    <packageName>odata.msgraph.client</packageName>
                                </schema>
                                <schema>
                                    <namespace>microsoft.graph.callRecords</namespace>
                                    <packageName>odata.msgraph.client.callrecords</packageName>
                                </schema>
                            </schemas>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

[rmkellogg]

I am using the following fragment:

           <plugin>
                <groupId>com.github.davidmoten</groupId>
                <artifactId>odata-client-maven-plugin</artifactId>
                <version>${project.parent.version}</version>
                <executions>
                    <execution>
                        <id>generate-northwind-model</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <metadata>src/main/odata/Azure-Boards-Metadata-v3.0.xml</metadata>
                            <schemas>
                                <schema>
                                    <namespace>AzureBoardsModel</namespace>
                                    <packageName>odata.azure.boards.model</packageName>
                                </schema>
                                <schema>
                                    <namespace>ODataWebExperimental.AzureBoards.Model</namespace>
                                    <packageName>odata.azure.boards.model</packageName>
                                </schema>
                            </schemas>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
`

I essentially copied the contents of your odata-client-test-northwind project and dropped in my metadatafile.  

Mind you this is not critical for my usage.  I plan to use your POJOs with some modifications anyway.  Ticket was filed more as an FYI.  Appreciate you taking such an interest though.

[rmkellogg]

Now I see, I should have been manually mapping the namespace to a specific package name. Usage error on my part. I just did a quick search and replace on the pom.xml file without really understanding it fully.

[rmkellogg]

If only all software companies were this quick to resolve issues. Let me do a pull and validate your fix works without manual mapping required.

[davidmoten]

Good, that should have you sorted. I've added reserved word handling for the default namespace to package name mapping in #40.

[rmkellogg]

Validated against pkg-reserved-word. All is great now. Many thanks.

[davidmoten]

Beaut, I've merged the PR and the new version will be on Maven Central in an hour or two.

[davidmoten]

BTW I've been overlooking the ability of odata-client to generate clients for all these other odata services in the Microsoft stable. These are part of the Analytics platform I take it. Did you get that metadata file via https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/$metadata?

[rmkellogg]

The file provided was from https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0/$metadata. At this time v4.0-preview is available though. Attached for your convenience.

Azure-Boards-Metadata-v4.0-preview.zip

[davidmoten]

I'm assuming the next step for you would be configuring the client especially authentication. I've made things very smooth for the Graph api, I'd be happy to help you out with clients for Analytics as well (and publish the useful bits for use by others).

[davidmoten]

The thing that throws me about those urls is the organization field. To what extent does the metadata vary from organization to organization? If the only variation was on version then I could generate pre-built clients for Analytics services. I wonder if these services will turn up in the Graph API?

[davidmoten]

Quick question: what are the possible values for {project}? I'm showing poor google-fu.

[rmkellogg]

Azure Boards supports the creation of custom fields on Work Items in the Process definition of an Organization. If you add it to the Process, it appears in the $metadata returned by the following four EntityTypes: WorkItem, WorkItemSnapshot, WorkItemBoardSnapshot & WorkItemBoardSnapshot. The metadata is identical for all projects under an organization.

Azure Boards does not seem to allow for any other custom field definitions. I have installed some Extensions which I know store data but that does not appears in the $metadata returned.

Here is a snippet from the metadata

<Property Name="Custom_TFSID" Type="Edm.String">
<Annotation Term="Display.DisplayName" String="TFS ID"/>
<Annotation Term="Ref.ReferenceName" String="Custom.TFSID"/>
</Property>

The Organization ID and Project ID used as part of the URL are unique and provided by the customer.

For my authentication test app, I am using an API token associated with my email address.

If I get some time this weekend, I will try to use your client as well. Initially was just going to use the entities and manually bind to the REST response. Thanks.

[rmkellogg]

Reference to Azure Boards Documentation: https://docs.microsoft.com/en-us/azure/devops/organizations/settings/work/add-custom-field?view=azure-devops

[davidmoten]

Thanks for the info @rmkellogg. I've found the whole-of-org analytics metadata for my org at https://analytics.dev.azure.com/MYORG/_odata/v3.0/$metadata. The auth stuff should be the same as MsGraph so we should be able to build an analytics client as per the beta client https://github.com/davidmoten/odata-client/blob/master/odata-client-msgraph-beta/src/main/java/com/github/davidmoten/msgraph/beta/MsGraph.java (without the explorer() method). Should be easy, I can add a demo project for Analytics and people can modify it as they see fit with their own metadata.

[davidmoten]

I've added the demo module https://github.com/davidmoten/odata-client/tree/master/odata-client-microsoft-analytics-template to odata-client. It demonstrates exactly how to build a client for use with Analytics services (that share the MsGraph oauth2 authentication method). I haven't tested it against a real service yet, feel free to try it!

The changes to support your own metadata are

• put your metadata into src/main/odata/
• change the pom to point to your metadata
• fiddle with the package name mappings in the plugin in the pom as you like
• generate the code: mvn clean install
• create a client in code as per AnalyticsTest.java (very easy).

I'll add a README.md to the template project in a bit.

[davidmoten]

Thanks for the demo project to connect to. I've enabled the client builder support basic authentication and works. Take it for a spin! See https://github.com/davidmoten/odata-client/blob/master/odata-client-microsoft-analytics/src/test/java/com/github/davidmoten/microsoft/analytics/AnalyticsDemoMain.java.

[davidmoten]

I've updated it again, even simpler:

Container client = Analytics
    .service(Container.class) 
    .baseUrl(baseUrl) 
    .basicAuthentication(username, password)
    .build();

[rmkellogg]

Tested and confirmed everything works splendidly. Many thanks.

Would suggest you rename the project from odata-client-microsoft-analytics-template to odata-client-microsoft-azure-boards-template. The technique might apply to Microsoft Analytics in general but I cannot confirm. Similar change applies to naming of metadata files.

Also, please note that password in this case is actually a Personal Access Token. The Personal Access Token will require access to the Analytics Service permission to utilize the OData endpoint.

[rmkellogg]

One more fascinating observation/caveat, I have defined the custom field called "Custom_TFSID" as shown above at the Organization Process level. It is returned in the Organization metadata. I use this within my Project and data exists yet it is not returned in the Project metadata. So any custom fields defined within Azure Boards are not available via OData which is a significant limitation to its usefulness.

[davidmoten]

That's interesting, can you use the organisation level metadata with the /organisation/project baseUrl?

[davidmoten]

Re naming, Analytics for DevOps seems to be how Microsoft describes it. https://docs.microsoft.com/en-us/azure/devops/report/extend-analytics/quick-ref?view=azure-devops. Based on that the name seems alright (adding devops to the name is perhaps a good idea) and I'm happy to receive feedback from someone that it doesn't work with service X later and then address that.

I think I'll also drop the template suffix from the artifact name because it will work standalone but I'll document in READMEs how to modify the project with custom metadata.

I grabbed your organization level metadata to test with the /org/project url but it appears you've removed the Custom_TFSID field?

[davidmoten]

@rmkellogg If you have time to continue discussing, I've moved this discussion to #41. I'll close this issue now as it has been fixed.