VcsSupport Question

I have been working on an MKS VcsSupport plugin for the last week and have now reached a point where I need to make use of the PatchBuilder class. I am unable to find any javadoc in the openapi jar.

I have taken a look at the decompiled sources of the CVS plugin, but its less than clear on the intended usage of the class. Is there somewhere we can get ahold of the javadoc for this class, as well as the ModificationData and VcsChange classes?

Thanks!

Steve

6 comments
Comment actions Permalink

Hello Steven,
Sorry for delay.

I've just added some comments to the PatchBuilder interface, please feel free to ask me any questions or to comment any vague pieces of this description. Here is commented interface:

/*

  • Copyright (c) 2006, JetBrains, s.r.o. All Rights Reserved.

*/

package jetbrains.buildServer.vcs.patches;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;

/**

  • This interface allows you to create information about files changed between two versions.

*/
public interface PatchBuilder {

/**

  • Invoke this method if some file has been deleted in the next version as compared with the previous one.

  • @param file file relative to the current working directory.

  • @param deleteParentDirectoryIfEmpty pass true if you want patcher to delete parent

  • directory if it became empty after the deletion.

  • @throws IOException

*/
void deleteFile(File file, boolean deleteParentDirectoryIfEmpty) throws IOException;

/**

  • Invoke this method if some directory has been deleted in the next version as compared with the previous one.

  • @param file directory relative to the current working directory.

  • @param deleteParentDirectoryIfEmpty pass true if you want patcher to delete parent

  • directory if it became empty after the deletion.

  • @throws IOException

*/
void deleteDirectory(File file, boolean deleteParentDirectoryIfEmpty) throws IOException;

/**

  • Invoke this method if some text file content has been changed or text file has been created in the next version as compared with the previous one.

  • @param localFile file relative to the current working directory

  • @param fileMode file mode in the linux style. If it doesn't matter for you set it to null.

  • Set this parameter to not null if its value changes something, for example, pass "ugo+x" if you want the file to be executable

  • and null otherwise. It is performance issue because set file mode will create a lot of processes on the Linux.

  • @param input input stream containing the file content.

  • @param length length of the content.

  • @param lineSeparator text content line separator. Set null if you want to use system dependant separators. Use "changeOrCreateBinaryFile"

  • if you want file to keep existing separators.

  • @throws IOException

*/
void changeOrCreateTextFile(File localFile, String fileMode, InputStream input, long length, byte[] lineSeparator) throws IOException;

/**

  • Invoke this method if some binary file content has been changed or binary file has been created in the next version as compared with the previous one.

  • This method can be used for text file also if you want to keep existing line separators inside the file.

  • @param file file relative to the current working directory.

  • @param fileMode file mode in the linux style. If it doesn't matter for you set it to null.

  • Set this parameter to not null if its value changes something, for example, pass "ugo+x" if you want the file to be executable

  • and null otherwise. It is performance issue because set file mode will create a lot of processes on the Linux.

  • @param input input stream containing the file content.

  • @param length length of the content.

  • @throws IOException

*/
void changeOrCreateBinaryFile(File file, String fileMode, InputStream input, long length) throws IOException;

/**

  • Invoke this method if some directory has been created in the next version as compared with the previous one.

  • @param file file relative to the current working directory.

  • @throws IOException

*/
void createDirectory(File file) throws IOException;

/**

  • Invoke this method if some binary file content has been created in the next version as compared with the previous one.

  • This method can be used for text file also if you want to keep existing line separators inside the file.

  • @param file file relative to the current working directory.

  • @param fileMode file mode in the linux style. If it doesn't matter for you set it to null.

  • Set this parameter to not null if its value changes something, for example, pass "ugo+x" if you want the file to be executable

  • and null otherwise. It is performance issue because set file mode will create a lot of processes on the Linux.

  • @param input input stream containing the file content.

  • @param length length of the content.

  • @throws IOException

*/
void createBinaryFile(File file, String fileMode, InputStream input, long length) throws IOException;

/**

  • Invoke this method if some text file has been created in the next version as compared with the previous one.

  • @param file file relative to the current working directory

  • @param fileMode file mode in the linux style. If it doesn't matter for you set it to null.

  • Set this parameter to not null if its value changes something, for example, pass "ugo+x" if you want the file to be executable

  • and null otherwise. It is performance issue because set file mode will create a lot of processes on the Linux.

  • @param input input stream containing the file content.

  • @param length length of the content.

  • @param lineSeparator text content line separator. Set null if you want to use system dependant separators. Use "createBinaryFile"

  • if you want file to keep existing separators.

  • @throws IOException

*/
void createTextFile(File file, String fileMode, InputStream input, long length, byte[] lineSeparator)
throws IOException;

/**

  • Allows you to switch on to the specified directory and clear its content. You have to build changed file informathion for such a kind

  • of a directory not between two specified revisions but get all files for the second version because there will not be "start" version,

  • it will be cleaned.

  • @param workingDir new working directory. Path relative to the initial directory, not to the current one.

  • @throws IOException

*/
void setAndClearWorkingDirectory(final String workingDir) throws IOException;

/**

  • Allows you to switch on to the specified directory keeping old content of this directory.

  • @param workingDir new working directory. Path relative to the initial directory, not to the current one.

  • @throws IOException

*/
void setWorkingDirectory(final String workingDir) throws IOException;
}

Thanks!

0
Comment actions Permalink

Thanks Oleysa.

Would you mind creating documentation for ModificationData and VcsChange as well?

Also, once this plugin is complete, what is the process to follow to get this submitted to the community at-large?

Thanks!

Steve

0
Comment actions Permalink

Sure.
The only commented method of ModidifcationData is its constructor, actually
it is the only method you have to use in production:
/**

  • This constructor has to be used in production code to create

ModificationData instance

  • @param changeDate date of the change. Used in presentation purposes

only.

  • @param changes list of all files affected by this modification.

  • @param description commit message.

  • @param user user name in the version control.

  • @param vcsRoot current settings.

  • @param version repository version right after the modification. Has to

have

  • the same meaning as VcsSupport.getCurrentVersion.

  • @param displayVersion repository version right after the modification

in the human

  • readable format. Used for presentation purpose only.

*/
@SuppressWarnings({"MethodWithTooManyParameters"})
public ModificationData(final Date changeDate,
final List]]> changes,
final String description,
final String user, final VcsRoot vcsRoot, final
String version,
final String displayVersion) {
this(changeDate, changes, description, user, vcsRoot, version,
displayVersion, changes.size());
}

as well as VcsChange:
/**

  • Creates new VcsChange instance.

  • @param type change type. Can be one of 4 kinds. Based on this type

files in change are shown in corresponding colour.

  • @param changeName string representation of the change kind. Should be

in human readable format.

  • @param fileName string representation of the file in repository. Should

be in human readable format.

  • VcsSupport has to be able to deal with this path, return file content

by specified VcsChange.

  • @param beforeNum file revision before the change. Can be repository

version before change.

  • @param afterNum file revision after the change. Can be repository

version after change.
*/
public VcsChange(@NotNull Type type, @NotNull final String changeName,
@NotNull final String fileName, String beforeNum, String afterNum) {
myChangeTypeName = changeName;
myFileName = fileName;
myType = type;

myBeforeChangeRevisionNumber = beforeNum;
myAfterChangeRevisionNumber = afterNum;
}

Shell I provide some additional information?

As for your question about publishing this plugin, at the moment all
TeamCity plugin are written by ourselves so there is not any process how to
publish third-party plugin. But let us know when your plugin is ready, we'll
do something (for example, we can add link to it on our confluence).

--
Olesya Smirnova
JetBrains, Inc
http://www.jetbrains.com
"Develop with pleasure!"


"Steven Stallion" <no_reply@jetbrains.com> wrote in message
news:17104147.1162214489123.JavaMail.itn@is.intellij.net...

Thanks Oleysa.

>

Would you mind creating documentation for ModificationData and VcsChange
as well?

>

Also, once this plugin is complete, what is the process to follow to get
this submitted to the community at-large?

>

Thanks!

>

Steve



0
Comment actions Permalink

Thanks again Oleysa.

Once this gets finished, I will write a VcsSupport How-To guide. This has been quite an adventure, but very much worth it IMHO.

Steve

0
Comment actions Permalink

Good day.

I also trying to add support for new VCS myself and there are several problems I run against. So I chose this thread to ask my question.

Can you explain architecture of yours VcsSupport model?

Here are some of my concrete questions (but it will be nice if your not only answer them but notice what is the most important to know/understand for me from your point of view)

So

1) I decompiled existing implementations and found that their behaviour are not the same. May be these are differences of VCSs (I am really skin-deep know with CSV, Perforce and Subversion)
but why in some of implementations method

byte[] getContent(final VcsModification vcsModification,
final VcsChange change,
final VcsChange.ContentType contentType,
final VcsRoot vcsRoot) throws VcsException;

simply readdresses its behaviuor to

byte[] getContent(final String filePath, final VcsRoot versionedRoot, final String version) throws VcsException;

while in others it has its own one. Please, detail what is the difference of these methods (why they have different implementations)?


2) I see "Remote Run" + "Delayed Commit" as the main advantage of your decision (especially for my team), so I wonder will I need to add any changes to IDEA's VCS support plugin also or server side implementation of VCS is enough?

3) How my personal changes (being loaded on server during "Remote Run") are combined with changes loaded from VCS. Need I add some support for this point.

Please, try to answer on my questions.

Thank you.

0
Comment actions Permalink

Can you explain architecture of yours VcsSupport model?

What exactly are you interested in?
VcsSupport is very simple thing :) - it collects changes between 2 versions
and builds "patches", changes made between two versions to free agents from
version control communication capabilities. Both of getContent are used from
the plugin only (at the moment).
Also VcsSupport should provide its configuration details as a jsp page.

There is changes collector which from time to time asks VcsSupport what
changes appeared since last detected version (its a vertion of the latest
modification or current version if there are no changes)

When build is starting server asks VcsSupport to build patch between version
been applied to an agent last time and current version.

These operations are working with VcsRoot, configured connection to some
vertion control server.


>Please, detail what is the difference of these methods (why they have
>different implementations)?

byte[] getContent(final VcsModification vcsModification,
final VcsChange change,
final VcsChange.ContentType contentType,
final VcsRoot vcsRoot) throws VcsException;

You have file change. It contains file path you defined for this file and
information if system asks you for file revision before change (content
type). You can choose any style for a file path in the change, for example
svn uses full url.
Used to show diff between before and after contents.

byte[] getContent(final String filePath, final VcsRoot versionedRoot,
final String version) throws VcsException;

You have file relative path so you have to translate it to the "url" which
you can use to request file content from the vcs server.
Also when there is file change with revisions before and after you can use
one of them to request content, but is this method there is only version of
the whole repository.
Used to calc diff file in the IDEA editor and file content corresponding
some specific build.

2) I see "Remote Run" + "Delayed Commit" as the main advantage of your
decision (especially for my team), so I wonder will I need to add any
changes to IDEA's VCS support plugin also or server side implementation of
VCS is enough?

If your changes are shown in the "Changes View" tab window and can be
submitted from there it's enough.

3) How my personal changes (being loaded on server during "Remote Run")
are combined with changes loaded from VCS. I'm not sure I've really got
it. Personal changes will apply "over" latest repository version. Changed
file content will be replaced, it will not try to merge the changes.
Delayed commit also does not support merge, so if there is another change
for the file it will not be submitted.

--
Olesya Smirnova
JetBrains, Inc
http://www.jetbrains.com
"Develop with pleasure!"


"temporary" <temporary@hotmail.ru> wrote in message
news:32335781.1162243856938.JavaMail.itn@is.intellij.net...

Good day.

>

I also trying to add support for new VCS myself and there are several
problems I run against. So I chose this thread to ask my question.

>

Can you explain architecture of yours VcsSupport model?

>

Here are some of my concrete questions (but it will be nice if your not
only answer them but notice what is the most important to know/understand
for me from your point of view)

>

So

>

1) I decompiled existing implementations and found that their behaviour
are not the same. May be these are differences of VCSs (I am really
skin-deep know with CSV, Perforce and Subversion)
but why in some of implementations method

>

byte[] getContent(final VcsModification vcsModification,
final VcsChange change,
final VcsChange.ContentType contentType,
final VcsRoot vcsRoot) throws VcsException;

>

simply readdresses its behaviuor to

>

byte[] getContent(final String filePath, final VcsRoot versionedRoot,
final String version) throws VcsException;

>

while in others it has its own one. Please, detail what is the difference
of these methods (why they have different implementations)?

>
>

2) I see "Remote Run" + "Delayed Commit" as the main advantage of your
decision (especially for my team), so I wonder will I need to add any
changes to IDEA's VCS support plugin also or server side implementation of
VCS is enough?

>

3) How my personal changes (being loaded on server during "Remote Run")
are combined with changes loaded from VCS. Need I add some support for
this point.

>

Please, try to answer on my questions.

>

Thank you.



0

Please sign in to leave a comment.