Contributing to Java: The JSPA and the OCA

Disclaimer: This post is written by developers to demystify the process and some of the differences between the JSPA (Java Specification Participation Agreement) and the OCA (Oracle Contribution Agreement). Both of these may have legal implications to intellectual property rules that might be written into your employment contract. If you are in any doubt please seek legal advice before signing one of these contracts, the last thing either you or the community wants is for you to find yourself in a legal conflict.

If you are thinking about contributing to Java there are two levels on which you can get involved. Depending on what you want to contribute you will need to sign either one or both of the JSPA (Java Specification Participation Agreement) or the OCA (Oracle Contribution Agreement).

JSPA

The Java Specification Participation Agreement is an 11 page document enabling you to participate towards the JSR (Java Specification Requests) process.

• The JSPA enables you to contribute to JSRs and sit on the expert group of individuals representing that change.
• Your employer may have already signed the JSPA, in the first instance you should check with them as you might already be covered for your participation by their contract.
• If your employer hasn’t signed the JSPA, you will probably want to participate as an individual (there is a cost associated with company memberships, however an individual membership is free of charge).
• Your employer needs to agree with you signing the JSPA (even as an individual) and your employer needs to sign your individual JSPA paperwork. Note: the signature needs to meet certain standards – if you’re not sure you need to look at the Oracle website, especially if it’s a squiggle! (from experience)
• I worked for a large investment bank and this was not a problem to be signed off by the legal team, but it did take around a month. So if you are thinking of participating in a JSR it’s a good idea to get this signed off early.
• Once you send to Oracle the process is usually fairly quick to resolve, you can either fax (if that still exists where you are) or E-Mail each of the pages back as a PDF.

OCA

The OCA is required for direct code based contributions that are to be checked in to Java. It is a short single page document.

• If you’re working on Open JDK and your work is approved for submission you will need to have one of these.
• The essence of this agreement is to share the ownership of the change between yourself and Oracle.
• If you’re thinking about taking this path it’s only a simple one page document that is quick to complete, so I recommend doing this upfront.
• If you are going through your employers approval process it is potentially a good idea to try get both of these agreements signed off at the same time if you need to.

One final thing to note is that you can still attend hack days and bug fixing days without having the above signed, so if you’re not sure about how to get started, a hack day, Adopt-A-JSR or Adopt Open JDK  is for you.

Changes to the LJC JCP Committee

Changes to the LJC JCP Committee

As mentioned in a previous post the committee is very pleased to have been re-elected to sit on the JCP committee. Everyone who works on the LJC committee does this voluntarily and in their spare time. Naturally as other commitments come around for personal and/or other opportunities we always welcome new faces and bid farewell to those who have contributed.

On this occasion, Richard Warburton is stepping down from the LJC JCP to focus on other initiatives within the Java community. Richard has worked on countless initiatives within the LJC JCP and first became interested in the cause when he first moved to London and met Jim Gough in a bar at the monthly developer sessions. Since then he has significantly contributed to both project lambda for Java 8 and the Date Time API, also for Java 8. Working with the rest of the committee Richard helped to setup sone of the corner stones that launched the Adopt-a-JSR initiative and running hack days in multiple countries. It is fair to say that Richard has aided the delivery of Java 8 and many of its newer features.

Richard is well known to the spec leads of the major JSR projects due to his insight and feedback into the development of the features. Although Richard is leaving the LJC JCP group he will still be actively involved in the community and through the Adopt-A-JSR program.

We would like to thank Richard for all his hard work and wish him all the best for the future.

Jim Gough on behalf of the LJC JCP Committee

JSR-310 Method Naming Survey Results

As part of the London Java Communities efforts to help out in JSR-310 efforts, we have been working with Stephen Colebourne to gather the feedback of the community on method naming conventions that would potentially be used in the upcoming implementation. After all, it is hoped that everyone in the Java world writing systems using dates will be potentially using the API from Java 8 onwards.

The intention of this blog post is to publicise the results and to encourage you to participate in the discussion. We are at the crossroads of finalising design and adapting the already comprehensive implementation to match the requirements. Please join us on the mailgroup and continue the discussion: mail group

There are 9 public questions that will be broken down into the general responses. The response has been immense, and behalf of everyone involved with the project I’d like to take this opportunity to thank you for your participation. The total number of surveys received was 1824. These results will contribute towards steering the API changes discussed on the mailing list.

The statistics below are summary statistics for the main categories, a full CSV of all anonymous responses is available here.

1. It is planned to have an enum for the month-of-year (January to December). What should this class be called?

• 89.21% chose the format Month – eg. Month.APRIL.
• 8.55% chose the format MonthOfYear – eg. MonthOfYear.APRIL.
• 2.24% gave an alternate response.

2. There will be a class representing a date on its own (no time, or time-zone). Thinking about this class, what set of methods would you prefer to use.

• 51.07% chose getYear(), getMonth(), getDay(), getDayOfYear(), getDayOfWeek().
• 37.30% chose getYear(), getMonth(), getDayOfMonth(), getDayOfYear(), getDayOfWeek().
• 9.44% chose getYear(), getMonthOfYear(), getDayOfMonth(), getDayOfYear(), getDayOfWeek().
• 2.19% gave an alternate response.

3. Thinking specifically about getDay() vs getDayOfMonth(), which of these statements do you agree with? (This was a select multiple question)

• 23.81% chose if I saw getDay() I would assume it was day-of-month.
• 20.33% chose I would quickly learn that getDay() meant day-of-month.
• 19.88% chose while it is longer, getDayOfMonth() is a lot clearer.
• 16.63% chose getDay() is not clear without reading Javadoc.
• 15.83% chose getDayOfMonth() is too long.
• 3.52% gave an alternate response.

4. There will be a class representing a time-of-day on its own (no date, or time-zone). Thinking about this class, what set of methods would you prefer to use?

• 72.44% chose getHour(), getMinute(), getSecond(), getNano().
• 13.30% chose getHour(), getMinute(), getSecond(), getNanoOfSecond().
• 8.04% chose getHourOfDay(), getMinuteOfHour(), getSecondOfMinute(), getNanoOfSecond().
• 6.23% gave an alternate response.

5. The month-of-year can be represented as both an int and as an enum. How should method access to this be achieved?

• 58.29% chose only have a method returning the enum, with the int value available via a method on the enum.
• 12.31% chose getMonthValue() returns an int; getMonth() returns an enum.
• 8.11% chose getMonth() returns an int; getMonthOfYear() returns an enum.
• 7.08% chose only have a method returning the int, removing the enum from the API.
• 7.08% chose getMonthInt() returns an int; getMonth() returns an enum.
• 3.91% chose getMonthOfYear() returns an int; getMonth() returns an enum.
• 3.22% gave an alternate response.

6. What factors should drive the method naming choice?

Question	Agree: 1	2	3	4	5: Disagree	Not sure	#
6.1 Shortest possible	20.45% (346)	22.75% (385)	21.28% (360)	13.71% (232)	19.03% (322)	2.78% (47)	1692
6.2 Pattern based	31.36% (519)	32.51% (538)	16.19% (268)	4.95% (82)	2.05% (34)	12.93% (214)	1655
6.3 Clear when read	65.61% (1139)	23.33% (405)	6.05% (105)	4.09% (71)	0.23% (4)	0.69% (12)	1736
6.4 Verbose	7.61% (125)	13.40% (220)	28.38% (466)	22.41% (368)	21.56% (354)	6.64% (109)	1642
6.5 Unambiguous	44.14% (746)	29.64% (501)	15.86% (268)	5.27% (89)	2.37% (40)	2.72% (46)	1690
6.6 Quick to write	17.15% (286)	23.14% (386)	26.92% (449)	16.91% (282)	13.37% (223)	2.52% (42)	1668
6.7 Consistent	64.57% (1099)	23.80% (405)	6.17% (105)	3.53% (60)	0.41% (7)	1.53% (26)	1702
6.8 Balance of short and clear	48.93% (823)	27.35% (460)	14.15% (238)	5.35% (90)	1.84% (31)	2.38% (40)	1682
6.9 No need to read Javadoc	32.15% (542)	30.72% (518)	20.94% (353)	9.13% (154)	4.63% (78)	2.43% (41)	1686

7. Too large to publish easily in the blog.

8. Have you used Joda-Time?

• 41.48% chose never.
• 36.34% chose occasionally.
• 22.18% chose frequently.

9. How much experience do you have with Java?

• 69.95% chose more than 5 years.
• 22.94% chose 2-5 years.
• 4.62% chose less than 2 years.
• 2.48% chose Java is not my main language.

What’s the point in a TCK, and why should you care?

As part of the London Java Community’s Adopt a JSR program, I took on the role of increasing awareness on JSR-310. JSR-310 is the proposed solution for improving the current data and time system within Java. For more information on JSR-310 please view this previous blog post. Following introducing JSR-310 to the London Java Community I have also become involved in planning a potential TCK (Technology Compatibility Kit) for JSR-310. When I first began the task I asked myself a few questions, which I will aim to answer in this blog post. The format of the post will be in questions and answer, so the reader can quickly skip through the topics they are not interested in. There will also be some more extended points within the post on the work we are currently undertaking as part of the London Java Community to contribute to the TCK for JSR-310.

Why should general Java developers care about JSR-310 and the TCK?

Most developers have used the current date APIs that are available in Java. They’re difficult to use, often lead to unexpected results and have a general confusion about them. JSR-310 aims to address these problems and ensure a better system for the future of Java. If contributions are not made by the community and Java developers this important JSR will miss the deadline for Java 8. My aim is to help get this through to Java 8 and I’m looking for as many people in the community to enable us to get there. Please feel free to contact me for more information:

• E-Mail
• Twitter @goughjam

What is a TCK? What are the terms that surround the JCP on this topic?

Before you can appreciate the reason for a TCK the first step is understanding the separation of concerns between the JSR (Java Specification Request) and the RI (Reference Implementation). The JSR has the purpose of stipulating the exact requirements of an implementation and is effectively the basis for the JavaDoc style interfaces, rather than getting bogged down in the implementation details. The reference implementation’s job is to be the code that fulfills the requirements, it should do no more and no less than what is required from the specification. The job of the TCK is to mediate the specification against the actual implementations, keeping in mind that there might be more that one implementation for a specific JSR.

What’s the difference between unit testing and TCK testing? What do both address? Is there any overlap?

The purpose of a TCK is to test the “conformance” of an implementation against a JSR, but it’s more than just that. It is a suite of tools, a test framework and documentation to allow someone to take the JSR and understand how the implementation must behave to pass the kit. Unit tests are internal to the reference implementation and are not necessarily going to provide the full suite and documented nature of a TCK. Is there opportunity for reuse, definitely! However the unit tests that might be reused from an existing implementation need to be selected with care. The tests should only be testing the specification rather than any specific functionality that could be internal to an implementation. In the example of ThreeTen the strategy will be to view the JSR Early Draft Review independently from the code base that already exists to ensure a high quality TCK is created.

What makes up a TCK?

As mentioned the TCK is suite of tools to allow an implementer to create a successful reference implementation. It also requires careful planning, this is the phase we are landing in now for JSR-310. We will be looking over the coming weeks to produce the following plans; project, test, integration, documentation and QA plans. The previous sentence is quite work heavy to look at on first glance and immediately it’s clear to see that the TCK is a project and application in itself.

The TCK needs to have the concept of conformance rules. These rules will measure the success of whether the implementation conforms to the specification. The test suite is a collection of conformance tests. The TCK should also allow the identification of methods that might be outside of the JSR, additional methods should cause the test to fail with a detailed description of the failure.

Because this is a piece of software what will be used by other developers, the error messages that are generated from the TCK need to be logical and clear as to why that test failed. Reporting and good user feedback is part of this framework.

Following the completion of a JSR the TCK doesn’t end, it should enter a maintenance phase. It is possible that over time errors will be spotted in the TCK and this needs to managed over time.

What resources are required to build a TCK?

People! People from the community and experts from the Java ecosystem. However, before this can be done we need to ensure that the planning phase is well underway before the actual development can take place. For people interested in ThreeTen and JSR-310 please familiarise yourself with the following documents and websites:

• The JSR Specification
• ThreeTen Documentation
• ThreeTen on GitHub
• How to build a TCK
• Lightning talk introduction
• About a new date time API

How long is it going to take?

It depends on the number of test cases that are identified, this will be part of the planning phase. A potential formula directly from the How to build a TCK document:

(A-Num × CovBreadth ÷ DevRate) × NumEng = Test Development Time (in weeks)

Where: 

• A-Num is the number of testable assertions defined by the specification. 
• CovBreadth is the coverage breadth goal. For example, 0.75 for 75% breadth coverage.
• (Note that the ideal practice is to thoroughly test all elements which requires 100% breadth and depth coverage. Assertion breadth coverage of only 75% means that assertion testing is incomplete.)
• DevRate is the test development rate. According to Sun’s experience a typical test development rate is approximately 12.5 test cases per week for a test developer to write, document, and debug assertion test cases (including simple test framework development).
• NumEng is the number of engineers writing tests.

I will use the above to estimate a back of the envelope time frame for the TCK and the preparation.

How can you get involved?

We are looking for volunteers to help us build the TCK implementation and that effort will be increasing over the next few weeks. If you are interested or would like to know any more information please drop me an E-Mail. There are many levels at which you can be involved with a project like this, it might be that you’d like to write some technical documentation, or actually get stuck into the code. Whatever challenge you are looking for, we look forward to having you on board.

About JSR-310 – A New Java Date/Time API

Recently, the London Java Community was elected onto the JCP (Java Community Process) board. The JCP is the mechanism for developing standard technical specifications for Java technology. The London Java Community’s membership on the board enables us to deliver content on upcoming and in-progress Java Specification Requests (JSRs) back to our growing community. It also gives us the unique opportunity to engage people working on the JSR projects and developers who have expressed an interest in contributing. We’re currently trailing the process of adopting a JSR. Although the process has not yet been fully defined, the first example we have selected is JSR-310, an improvement to the Java date system. Last month I presented a lightning talk on the topic of JSR-310 and Java Dates. This blog post will go into detail on some of the current limitations of dates in Java and will discuss how you can get involved in the ThreeTen project. The London Java Community JCP group believes this is an important JSR and will lead to an improvement to all developers using Java. If you are interested in finding out more about the LJC/LCP committee please contact @kittylyst on twitter, or drop me an email for more information.

Dates are a critical part of most software applications. Data models that represent something in the real world nearly always depend on timings or times of occurrence. Originally, Java had the Date class. There are a number of good discussions that have documented the limitations of the original Java Date class. One of the largest issues is that dates are mutable and therefore not thread safe, leading to an immediate issue surrounding scaling out applications that make use of Dates. Furthermore, Date is a DateTime, but confusingly there are also wrappers around Date in java.sql package for this. The functionality in Date and sql.Date are so similar that, especially for new developers, it can be unclear when and where to use each. Finally, there is no support for TimeZones in Java Dates, so building systems running in different regions and converting back to a centralised TimeZone was very complicated before the introduction of the Calendar class.

The Calendar class was added to the language later for TimeZone support and for more complex date problems. The problem with calendar was that it was still mutable, and formatting a date directly from a calendar was impossible – once again pushing the developer to understand the exact details of each implementation and when to use each.

The following code example is from a presentation given at JavaOne several years ago which highlights the above in one code fragment. A simple and readable piece of code shows 6 different bugs:

//Bug 1, 2007 although you think this is the date you actually need to subtract 1900 to get the true representation
//Bug 2, 12 dates are indexed from 0 so, in this instance, 12 is out of bounds
Date date = new Date(2007, 12, 13, 16, 40);
//Bug 3, The timezone isn’t the ISO standard and requires and underscore to be correct
TimeZone zone = TimeZone.getInstance(“Asia/HongKong”);
//Bug 4, can’t create a Calendar from a date, you need to use a static instance of and then apply the date
Calendar cal = new GregorianCalendar(date, zone);
DateFormat fm = new SimpleDateFormat(“HH:mm Z”);
//Bug 5 and 6, can’t format on a calendar or a calendar object like this

String str = fm.format(cal);

Joda Time

Joda Time introduced several new key concepts into the Date arena that make working with Date and Times far simpler from a programmer perspective.

• Instant – There is a Joda-Time class of “Instant”. “DateTime” is also an instant, but one that adds getters for the human fields. DateTime is immutable and therefore thread safe. Immediately we have a good replacement for Date.

• Interval – An interval is a time measured from one instant to the another. The limitation here is that both end points are in the same Chronology and TimeZone.

• Duration – Duration is simply an amount of time measured in milliseconds, no timezone or chronology applies to a duration

• Period – A period of time time defined in terms of fields. This is a really useful feature for working with dates from a human aspect. Whilst machines represent underlying dates in long numbers, we still split things down into months, days and hours. Consider saying “one month from now” in February and then saying the thing same in May. Even though the month is the same, the underlying number of days varies. Periods allow the programmer to specify this kind of logic without having to convert to seconds and then add these to the value of the object.

• Chronology – From the developer perspective, a chronology is under-the-hood and is the calculation engine which holds the complex calendar rules. In most cases this, is is ignored as most users will be using ISO Chronology.

• TimeZones – A representation of the TimeZone held within a DateTimeZone class.

JSR 310

JSR-310 builds on many of the concepts that were introduced in Joda Time. However, to have the most robust implementation available for Java, there are some key issues in Joda Time that had to be addressed in JSR 310. So Joda Time is not without its flaws, but this doesn’t mean it shouldn’t be used; it’s currently the best production ready system there is. Stephen Colebourne covers this in his blog.

Human and Machine Timelines – I was born on 29th September 2005, this is a human representation – a Java representation is the number of milliseconds since 1970-01-01T00:00Z. JSR 310 separates the concepts out in the underlying implementation to make intent clear.

Pluggable Chronology – This can introduce unexpected state to the system by its pluggable nature. Consider calling the month of the day, you could get 13 if the chronology was incorrectly set. It is likely that people don’t check this before they make the call. Keeping these things separate is good programming practice leading to better unit testing and fewer curve balls when debugging problems later.

Nulls – The treatment of null values is always up for debate, nulls could be treated as the epoch, rather than a null value. Having this fuzzy behaviour could lead to bugs where you simply didn’t realise that you had passed a null by hiding errors. JSR-310 will seek to treat nulls as exactly that, and not assume they are the epoch.

Internal Implementation – Most user interacting with dates may not realise the depth of the implementation that is required around such a system, for example most people will use standard chronologies and calculations with dates. However, the internal computations are complex, especially when coupled with chronologies and the human machine timelines. Ensuring this architecture is production standard for all users is not a simple task.

In JSR 310 some key decisions were made to move Joda Time forward by reworking some of the design concepts. What the user sees in the Joda time API is the tip of the iceberg. A lot had to change in order to have these design considerations in place.

The main issue that might compromise the inclusion into Java 8 will be around the TCK testing suite, which is likely to be required in addition to the unit tests provided with the current ThreeTen implementation.

Getting Involved

The ThreeTen project (the reference implementation of JSR-310) is now on GitHub, so contributions can be made and pulled into the project. ThreeTen is developed entirely in the open and there are still a number of things to be done. Contributions around documentation, testing and performance optimisations are currently up for grabs. One such example would be working out the best way to derive the OffsetDateTime from an instant.

Getting involved is as easy as entering a few git commands and joining the mail group.

Conclusion

JSR 310 is currently one of the key JSRs and any additional community support should help ensure that the project enters the earliest version of Java possible.

Jim Gough

Java 7 London Launch Event

Thursday the 7th of July saw one of the largest milestones in Java’s recent history, the much anticipated launch of Java 7. My initial reaction was it didn’t seem that long since Java 6 was launched, however it was almost 5 years ago, the technical equivalent of when dinosaurs still roamed the Earth.

I think it would be naive to assume that nothing has happened during the reign of Java 6, in fact it’s quite the opposite. The first step towards a better Java was the open sourcing of the JDK, giving developers the opportunity to fix and work directly on the platform. Although I don’t have a direct quote, at the LJC Open Conference in November 2010 it was stated that between the first version of Java 6 and the latest there was a performance gain of over 50%. In Java 6.14 we saw the introduction of the G1 Garbage Collector, another revolutionary change to the options that developers have in terms of tuning and performance. Politically Java has changed hands and governance, passing from Sun to Oracle, and people have their opinions on what this means for Java.

Up until Thursday I was very skeptical about where Oracle might go with Java and how that would change the language I have built my career on. Which brings me to the launch day itself, this began with a webcast held across the world by Oracle. If you missed the webcast you can view it here. We got to hear from some of the senior developers on the Java project, and also from community speakers from all corners of the globe. For the London Java Community, it was an absolute honor and pleasure to see a small group of users that has now risen to almost 1800 members, represented by Ben Evans. I really enjoyed the webcast and thank Adrian Woodhead at lastfm for their hospitality in hosting the webcast for other members of the LJC. That gesture of sharing is something that was also not far from the content of Oracle’s talk, as many people appreciate one of the biggest successes of Java is us – The Community. The value of this has certainly not been underestimated by Oracle and this was evident from the content of the webcast. So what do I think the main themes were to take away from the talk and the event?

• Java 7 is an evolutionary release not an revolutionary release – Mark Reinhold stated that one of the best things about Java 7 is the fact it is shipping.
• Increase in stability
• Increase in performance
• Increase in maintainability
• …Although not said explicitly, the feel of the community is Java 8 is definitely not as far away as the gap was from 6 to 7.

For the event there was then kind hospitality at the Oracle offices, with people from across the community together with a definite buzz and excitement in the room about Java once more.

What is new in Java 7? This could be an entire post/book in itself and each individual improvement could be gone into in great detail. I’ll attempt to pick out a few key points below and give links for more information. I’d also recommend reading Mark Reinhold’s blog. The best summary of the below I have read so far is in Java 7 developer MEAP, by Ben Evans and Martijn Verburg.

• JSR 292 Invoke Dynamic
• This is one of the major steps that we are seeing towards a change in the way that we view Java. What even is Java? I think we are seeing a separation of Java the language and the Java Virtual Machine. Strictly speaking, it’s not really the Java VM now, but just the VM. Highlighted by the gentleman in the video wearing a Python jacket over a Java T-Shirt, the VM is now home to many dynamic languages. Invoke Dynamic is another step towards the multi-language support for the JVM. Simply put it supports the invocation of allows a non-Java call to be made and for the linkage to be determined at runtime… OK that wasn’t so simple, but you can read more about the project here.
• JSR 334 Project Coin
• Project coin are all about small changes to the Java language to make life easier for daily use of the Java programming language. A few of my personal favorites are:
• Ability to switch on String! Finally, it’s only taken 15 years.
• Diamond Operator, no longer do you need to declare the generic expression on the right hand side if they are present on the left:
• Old Way: List<String> myFingersAlreadyHurt = new ArrayList<String>();
• New Way: List<String> jsr334SavedMyFingers = new ArrayList<>();
• try-with-resources – lets get rid of some boiler plate code
• You can find the full list here.
• Better Unicode Support
• Not too excited about this because it’s not a problem I run into. However, from speaking to a few people about this at the event – this was going to save them a lot of hassle.
• JSR 203: NIO.2 and File System
• Finally, we have a decent API for interacting with Files and a scalable approach to asynchronous I/O.
• I’m not an expert on the rest of this JSR yet, so might be worth having a read here if you want to know more.
• JSR 166y Fork Join Framework
• Doug Lea and his concurrency experts have created the Fork Join Framework. This allows for concurrent tasks that involve splitting a larger programmatic problem into smaller blocks of computation i.e. Merge Sort a nice framework in which to operate. The ForkJoinPool uses workers to perform the tasks placed upon it, which are also capable of stealing tasks from other workers if they are no longer busy.

I think the next few months in the Java community will be exciting ones, with July being very much the month of Cloud and is Java the right language for the cloud? For those in London that haven’t been along to a Java event yet, please come along and join us on meetup.com and join us at our developer pub session to get involved in the discussion.

James Gough