add extern uid field for create

[lamdav]

Closes #181

Let me know if you have another way in mind to support this.

[lamdav]

@gmessner

[gmessner]

@lamdav
There is 1 other field that should be added to UserApi.userToForm():

• shared_runners_minutes_limit (optional) - Pipeline minutes quota for this user

Also, to make the create and update more fluent, it would be good to have withXyz() methods added to User, this has been done in Project and a few other classes as I have added fields to them. Here's an example withXyz() method to add to User.java:

public User withEmail(String email) {
    super.setEmail(email);
    return this;
}

Only the 20 properties that are needed for creation/update should have with methods added. If you don't wish to do this, not a problem, I'll take care of it next time I make a mod to the project.

[gmessner]

@lamdav
After further examination of the current code base I've modified my original comment. That being said if you need this PR completed now I can approve and I will make the suggested changes in my next update.

[lamdav]

@gmessner
I added the fluent api builder pattern requested to User. The only thing I wasn't sure how to add is avatar which is supposed to be an image file.

One last note is that gitlab has also updated the api with reset_password and an order of precedence.

Either password or reset_password should be specified (reset_password takes priority).
I added this note into the docs; however, I am not sure how you want to modify the userToForm method.

One last thing, I also modified userToForm to prefer the parameters over the User object specification when constructing the form data.

[gmessner]

I should have made it clearer concerning avatar, password and reset_password, don't want any of these added to the user object, these are used on create or update only and are not returned in the user resource.

My plan was to add a create and update method that takes avatar, password, and reset_password as parameters, I believe avatar will need to do a file upload, which is currently only partially supported in GitLab4J so it will not be supported for now. You've pretty much done this except for reset_password. You should change this to have resetPassword as a parameter to the methods instead of being part of the User object.

Additionally, the implementation of userToForm() will not allow you to specify reset_password on create, with what you have right now, userToForm() will throw an exception if password is not set on creation. What you need to do is make both of these optional in the form and add this verification before the form is created:

if (create) {
   if ((password == null || password.trim().isEmpty()) && !resetPassword) {
       throw new RuntimeException("either password or reset_password must be set");
   }
}

[lamdav]

@gmessner
I extracted the password and reset_password out of the User object as parameters. I added two convenience methods createUser(User user, String password) and createUser(User user, boolean reset_password). I have added the code snippet you provided in the userToForm method.

Let me know if I misunderstood anything.

[gmessner]

Everything is spot on. Only one small issue is with the createUser() methods, since either password or reset_password must be set, it makes no sense to have a createUser(User user, boolean resetPassword) method. If resetPassword is false this method will throw an exception, as either a password must be provided or reset_password must be true. can we just combine these into one method:

createUser(User user, CharSequence password, boolean resetPassword)

You'll also notice that CharSequence is used instead of String, this is for security reasons, you can actually pass org.gitlab4j.api.utils.SecretString or String as the paramter.

BTW, thank you for all your contributions and working with me on these things.

[lamdav]

@gmessner
I considered this but I thought it was somewhat silly to expose a method that will throw an exception due to bad arguments (i.e. createUser(user, "", false) or createUser(user, "pass", true)). If the case is one or the other must be provided, I think it is less error prone to have methods such as createUserWithPassword(user, password) or createUserWithReset(user) where the latter method assumes reset_password = true. If I am understanding this correctly, I think this should address your concern in which the user could call createUser(user, false) for createUser(User user, boolean resetPassword).

In addition, after thinking about it more, perhaps we should throw the specific RuntimeException of IllegalArgumentException instead when both a password and resetPassword is provided or missing.

Let me know what you think and I'll make the change accordingly.

[lamdav]

I updated any uses of String password to be CharSequence password as suggested.

I decided to use IllegalArgumentException over the generic RuntimeException because I thought it was more appropriate. If you think otherwise, I will change it back.

I also went ahead and made the createUser update as mentioned previously as it was a quick fix. I am open to changing it all to one createUser method if you prefer. If so, let me know and I'll get it done by tomorrow.

[gmessner]

@lamdav
Throwing the IllegalArgumentException is the correct thing to do, makes it match how the GitLabForm().withParam() works, good catch.

I would rather not split createUser() out into two methods, you have the same problem you called silly with the new createUserWithPassword(user, password) method, it could be called with an empty or null password and an exception will be thrown. Additionally, it is OK to specify both a password and reset password, they are not mutually exclusive, the GitLab API will create the user with the specified password and send a reset password email (which the user could ignore).

Thanks again for all your diligent work and responses.

[lamdav]

@gmessner
I had a misunderstanding on the API. Thanks for clarifying. I had understood the API as a mutually exclusive specification for some reason. I have changed it to a single

createUser(User user, CharSequence password, boolean resetPassword)

as suggested.

[lamdav]

@gmessner
Thanks for the helpful comments and merging this. Can I get an ETA on the next release?

[gmessner]

@lamdav
Will be released later today.

[gmessner]

@lamdav
4.8.18 has been released.