/******************************************************************************* Copyright (c) 2011, Perforce Software, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PERFORCE SOFTWARE, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *******************************************************************************/ /******************************************************************************* * Name : Repository.Stream.cs * * Author : wjb * * Description : Stream operations for the Reposity. * ******************************************************************************/ using System; using System.Collections.Generic; using System.Linq; using System.Text; namespace Perforce.P4 { public partial class Repository { /// /// Create a new stream in the repository. /// /// Stream specification for the new stream /// The '-i' flag is required when creating a new stream /// The Stream object if new stream was created, null if creation failed /// The '-i' flag is added if not specified by the caller ///
///
p4 help stream ///
///
stream -- Create, delete, or modify a stream specification ///
///
p4 stream [-P parent] -t type name ///
p4 stream [-f] [-d] [-o [-v]] [-P parent] -t type name ///
p4 stream -i [-f] ///
///
A stream specification ('spec') names a path in a stream depot to be ///
treated as a stream. (See 'p4 help streamintro'.) The spec also ///
defines the stream's lineage, its view, and its expected flow of ///
change. ///
///
The 'p4 stream' command puts the stream spec into a temporary file and ///
invokes the editor configured by the environment variable $P4EDITOR. ///
When creating a stream, the type of the stream must be specified with ///
the '-t' flag. Saving the file creates or modifies the stream spec. ///
///
Creating a stream spec does not branch a new stream. To branch a ///
stream, use 'p4 copy -r -S stream', where 'stream' is the name of a ///
stream spec. ///
///
The stream spec contains the following fields: ///
///
Stream: The stream's path in a stream depot, of the form ///
//depotname/streamname. This is both the name of the stream ///
spec and the permanent, unique identifier of the stream. ///
///
Update: The date this stream spec was last changed. ///
///
Access: The date of the last command used with this spec. ///
///
Owner: The stream's owner. Can be changed. ///
///
Name: An alternate name of the stream, for use in display outputs. ///
Defaults to the 'streamname' portion of the stream path. ///
Can be changed. ///
///
Parent: The parent of this stream. Can be 'none' if the stream type ///
is 'mainline', otherwise must be set to an existing stream ///
identfier, of the form //depotname/streamname. ///
Can be changed. ///
///
Type: 'mainline', 'virtual', 'development', 'release' or 'task'. ///
Defines the role of a stream: A 'mainline' may not have a ///
parent. A 'virtual' stream is not a stream but an alternate ///
view of its parent stream. The 'development' and 'release' ///
streams have controlled flow. Can be changed. A 'task' ///
stream is a lightweight short-lived stream that only ///
promotes edited files to the repository; branched and ///
integrated files are stored in shadow tables that are ///
removed when the task stream is deleted or unloaded. ///
///
Flow control is provided by 'p4 copy -S' and 'p4 merge -S'. ///
These commands restrict the flow of change as follows: ///
///
Stream Type Direction of flow Allowed with ///
----------- ----------------- ------------ ///
development to parent stream 'p4 copy' ///
task to parent stream 'p4 copy' ///
release to parent stream 'p4 merge' ///
development from parent stream 'p4 merge' ///
release from parent stream 'p4 copy' ///
///
The [no]fromparent and [no]toparent options determine if ///
'p4 copy -S' and 'p4 merge -S' allow change to flow between ///
a stream and its parent. A 'virtual' stream must have its ///
flow options set as 'notoparent' and 'nofromparent'. Flow ///
options are ignored for 'mainline' streams. ///
///
Description: An optional description of the stream. ///
///
Options: Flags to configure stream behavior. Defaults are marked *: ///
///
unlocked * Indicates whether the stream spec is locked ///
locked against modifications. If locked, the spec ///
may not be deleted, and only its owner may ///
modify it. ///
///
allsubmit * Indicates whether all users or only the ///
ownersubmit of the stream may submit changes to the ///
stream path. ///
///
toparent * Indicates whether integration from the ///
notoparent stream to its parent is expected to occur. ///
///
fromparent * Indicates whether integration to the stream ///
nofromparent from its parent is expected to occur. ///
///
Paths: One or more lines that define file paths in the stream view. ///
Each line is of the form: ///
///
<path_type> <view_path> [<depot_path>] ///
///
where <path_type> is a single keyword, <view_path> is a file ///
path with no leading slashes, and the optional <depot_path> ///
is a file path beginning with '//'. Both <view_path> and ///
<depot_path> may contain trailing wildcards, but no leading ///
or embedded wildcards. Lines in the Paths field may appear ///
in any order. A duplicated <view_path> overrides its ///
preceding entry. ///
///
For example: ///
///
share src/... ///
import lib/abc/... //over/there/abc/... ///
isolate bin/* ///
///
Default is: ///
///
share ... ///
///
The <path_type> keyword must be one of: ///
///
share: <view_path> will be included in client views and ///
in branch views. Files in this path are accessible ///
to workspaces, can be submitted to the stream, and ///
can be integrated with the parent stream. ///
///
isolate: <view_path> will be included in client views but ///
not in branch views. Files in this path are ///
accessible to workspaces, can be submitted to the ///
stream, but are not integratable with the parent ///
stream. ///
///
import: <view_path> will be included in client views but ///
not in branch views. Files in this path are mapped ///
as in the parent stream's view (the default) or to ///
<depot_path> (optional); they are accessible to ///
workspaces, but can not be submitted or integrated ///
to the stream. ///
///
exclude: <view_path> will be excluded from client views ///
and branch views. Files in this path are not ///
accessible to workspaces, and can't be submitted ///
or integrated to the stream. ///
///
Paths are inherited by child stream views. A child stream's ///
paths can downgrade the inherited view, but not upgrade it. ///
(For instance, a child stream can downgrade a shared path to ///
an isolated path, but it can't upgrade an isolated path to a ///
shared path.) Note that <depot_path> is relevant only when ///
<path_type> is 'import'. ///
///
Remapped: Optional; one or more lines that define how stream view paths ///
are to be remapped in client views. Each line is of the form: ///
///
<view_path_1> <view_path_2> ///
///
where <view_path_1> and <view_path_2> are Perforce view paths ///
with no leading slashes and no leading or embedded wildcards. ///
For example: ///
///
... x/... ///
y/* y/z/* ///
///
Line ordering in the Remapped field is significant; if more ///
than one line remaps the same files, the later line has ///
precedence. Remapping is inherited by child stream client ///
views. ///
///
Ignored: Optional; a list of file or directory names to be ignored in ///
client views. For example: ///
///
/tmp # ignores files named 'tmp' ///
/tmp/... # ignores dirs named 'tmp' ///
.tmp # ignores file names ending in '.tmp' ///
///
Lines in the Ignored field may appear in any order. Ignored ///
names are inherited by child stream client views. ///
///
The -d flag causes the stream spec to be deleted. A stream spec may ///
not be deleted if it is referenced by child streams or stream clients. ///
Deleting a stream spec does not remove stream files, but it does mean ///
changes can no longer be submitted to the stream's path. ///
///
The -o flag causes the stream spec to be written to the standard ///
output. The user's editor is not invoked. -v may be used with -o to ///
expose the automatically generated client view for this stream. ///
('p4 help branch' describes how to expose the branch view.) ///
///
The -P flag can be used to insert a value into the Parent field of a ///
new stream spec. It has no effect on an existing spec. ///
///
The -t flag is used to insert a value into the type field of a ///
new stream spec and to adjust the default fromparent option ///
for a new 'release' -type stream. The flag has no effect on an ///
existing spec. ///
///
The -i flag causes a stream spec to be read from the standard input. ///
The user's editor is not invoked. ///
///
The -f flag allows a user other than the owner to modify or delete a ///
locked stream. It requires 'admin' access granted by 'p4 protect'. ///
///
///
/// /// /// To create a new mainline stream: /// /// /// Stream main = new Stream(); /// string mainTargetId = "//Rocket/mainline"; /// main.Id = mainTargetId; /// main.Type = StreamType.Mainline; /// main.Parent = new DepotPath("none"); /// main.Options = new StreamOptionEnum(StreamOption.None); /// main.Name = "mainline"; /// main.Paths = new ViewMap(); /// MapEntry p1 = new MapEntry(MapType.Import, new DepotPath("..."), null); /// main.Paths.Add(p1); /// MapEntry p2 = new MapEntry(MapType.Share, new DepotPath("core/gui/..."), null); /// main.Paths.Add(p2); /// main.OwnerName = "admin"; /// Stream mainline = rep.CreateStream(main, null); /// /// /// /// To create a new development type stream with the parent //Rocket/mainline: /// /// /// Stream dev = new Stream(); /// string developmentTargetId = "//Rocket/dev"; /// dev.Id = developmentTargetId; /// dev.Type = StreamType.Development; /// dev.Parent = new DepotPath("//Rocket/mainline"); /// dev.Name = "releasetest"; /// dev.Options = new StreamOptionEnum(StreamOption.None); /// dev.Paths = new ViewMap(); /// MapEntry devp1 = new MapEntry(MapType.Share, new DepotPath("..."), null); /// dev.Paths.Add(devp1); /// dev.OwnerName = "admin"; /// Stream dev1 = rep.CreateStream(dev, null); /// /// /// /// /// public Stream CreateStream(Stream stream, Options options) { if (stream == null) { throw new ArgumentNullException("stream"); } P4Command cmd = new P4Command(this, "stream", true); cmd.DataSet = stream.ToString(); if (options == null) { options = new Options(); } options["-i"] = null; P4CommandResult results = cmd.Run(options); if (results.Success) { return stream; } else { P4Exception.Throw(results.ErrorList); } return null; } /// /// Create a new stream in the repository. /// /// Stream specification for the new stream /// The Stream object if new stream was created, null if creation failed /// /// To create a new locked release type stream in the repository, with ignored and remapped /// paths: /// /// Stream s = new Stream(); /// string targetId = "//Rocket/rel1"; /// s.Id = targetId; /// s.Type = StreamType.Release; /// s.Options = new StreamOptionEnum(StreamOption.Locked | StreamOption.NoToParent); /// s.Parent = new DepotPath("//Rocket/main"); /// s.Name = "Release1"; /// s.Paths = new ViewMap(); /// MapEntry p1 = new MapEntry(MapType.Import, new DepotPath("..."), null); /// s.Paths.Add(p1); /// MapEntry p2 = new MapEntry(MapType.Share, new DepotPath("core/gui/..."), null); /// s.Paths.Add(p2); /// s.OwnerName = "admin"; /// s.Description = "release stream for first release"; /// s.Ignored = new ViewMap(); /// MapEntry ig1 = new MapEntry(MapType.Include, new DepotPath(".tmp"), null); /// s.Ignored.Add(ig1); /// MapEntry ig2 = new MapEntry(MapType.Include, new DepotPath("/bmps/..."), null); /// s.Ignored.Add(ig2); /// MapEntry ig3 = new MapEntry(MapType.Include, new DepotPath("/test"), null); /// s.Ignored.Add(ig3); /// MapEntry ig4 = new MapEntry(MapType.Include, new DepotPath(".jpg"), null); /// s.Ignored.Add(ig4); /// s.Remapped = new ViewMap(); /// MapEntry re1 = new MapEntry(MapType.Include, new DepotPath("..."), new DepotPath("x/...")); /// s.Remapped.Add(re1); /// MapEntry re2 = new MapEntry(MapType.Include, new DepotPath("y/*"), new DepotPath("y/z/*")); /// s.Remapped.Add(re2); /// MapEntry re3 = new MapEntry(MapType.Include, new DepotPath("ab/..."), new DepotPath("a/...")); /// s.Remapped.Add(re3); /// /// Stream newStream = rep.CreateStream(s); /// /// public Stream CreateStream(Stream stream) { return CreateStream(stream, null); } /// /// Update the record for a stream in the repository /// /// Stream specification for the stream being updated /// The Stream object if new stream was saved, null if creation failed /// /// To set the locked option on a stream: /// /// Stream streamToUpdate = rep.GetStream("//Rocket/GUI"); /// streamToUpdate.Options |= StreamOption.Locked; /// streamToUpdate = rep.UpdateStream(streamToUpdate); /// /// public Stream UpdateStream(Stream stream) { return CreateStream(stream); } /// /// Update the record for a stream in the repository /// /// Stream specification for the stream being updated /// The Stream object if new stream was saved, null if creation failed /// /// /// To update a locked stream when connected as an admin user: /// /// /// Stream streamToUpdate = rep.GetStream("//Rocket/GUI"); /// // set locked option /// streamToUpdate.Options |= StreamOption.Locked; /// streamToUpdate = rep.UpdateStream(streamToUpdate); /// streamToUpdate.Description = "edited"; /// string parent = streamToUpdate.Parent.ToString(); /// string type = streamToUpdate.Type.ToString(); /// streamToUpdate = rep.UpdateStream(streamToUpdate, /// new StreamCmdOptions(StreamCmdFlags.Force, parent, type )); /// /// public Stream UpdateStream(Stream stream, Options options) { return CreateStream(stream, options); } /// /// Get the record for an existing stream from the repository. /// /// Stream name /// There are no valid flags to use when fetching an existing stream /// The Stream object if new stream was found, null if creation failed /// /// /// Get the stream with the stream Id "//Rocket/GUI": /// /// /// string targetStream = "//Rocket/GUI"; /// Stream s = rep.GetStream(targetStream, null, null); /// /// /// Get stream spec for a new development type stream with the parent /// //Rocket/MAIN: /// /// /// string targetStream = "//Rocket/GUI2"; /// string parentStream = "//Rocket/MAIN"; /// Stream stream = rep.GetStream(targetStream, parentStream, /// new StreamCmdOptions(StreamCmdFlags.None, parentStream, /// StreamType.Development.ToString())); /// /// /// public Stream GetStream(string stream, string parent, Options options) { if (stream == null) { throw new ArgumentNullException("stream"); } P4Command cmd = new P4Command(this, "stream", true, stream); if (options == null) { options = new Options((StreamCmdFlags.Output), parent, null); } if (options.ContainsKey("-o") == false) { options["-o"] = null; } P4CommandResult results = cmd.Run(options); if (results.Success) { if ((results.TaggedOutput == null) || (results.TaggedOutput.Count <= 0)) { return null; } Stream value = new Stream(); value.FromStreamCmdTaggedOutput(results.TaggedOutput[0]); return value; } else { P4Exception.Throw(results.ErrorList); } return null; } /// /// Get the record for an existing stream from the repository. /// /// Stream name /// The Stream object if new stream was found, null if creation failed /// /// Get the stream with the stream Id "//Rocket/GUI": /// /// string targetStream = "//Rocket/GUI"; /// Stream s = rep.GetStream(targetStream); /// /// public Stream GetStream(string stream) { return GetStream(stream, null, null); } /// /// Get a list of streams from the repository /// /// options for the streams command /// A list containing the matching streams /// ///
p4 help streams ///
///
streams -- Display list of streams ///
///
p4 streams [-F filter -T fields -m max] [streamPath ...] ///
///
Reports the list of all streams currently known to the system. If ///
a 'streamPath' argument is specified, the list of streams is limited ///
to those matching the supplied path. ///
///
For each stream, a single line of output lists the stream depot path, ///
the type, the parent stream depot path, and the stream name. ///
///
The -F filter flag limits the output to files satisfying the expression ///
given as 'filter'. This filter expression is similar to the one used ///
by 'jobs -e jobview', except that fields must match those above and ///
are case sensitive. ///
///
e.g. -F "Parent=//Ace/MAIN & Type=development" ///
///
Note: the filtering takes place post-compute phase; there are no ///
indexes to optimize performance. ///
///
The -T fields flag (used with tagged output) limits the fields output ///
to those specified by a list given as 'fields'. These field names can ///
be separated by a space or a comma. ///
///
e.g. -T "Stream, Owner" ///
///
The -m max flag limits output to the first 'max' number of streams. ///
///
///
/// /// To get the first 3 development type streams with the parent //flow/mainline: /// /// /// IList<Stream> = rep.GetStreams(new Options(StreamsCmdFlags.None, /// "Parent=//flow/mainline & Type=development", null, "//...", 3)); /// /// public IList GetStreams(Options options, params FileSpec[] files) { P4Command cmd = null; if ((files != null) && (files.Length > 0)) { cmd = new P4Command(this, "streams", true, FileSpec.ToStrings(files)); } else { cmd = new P4Command(this, "streams", true); } P4CommandResult results = cmd.Run(options); if (results.Success) { if ((results.TaggedOutput == null) || (results.TaggedOutput.Count <= 0)) { return null; } List value = new List(); bool dst_mismatch = false; string offset = string.Empty; if (Server != null && Server.Metadata != null) { offset = Server.Metadata.DateTimeOffset; dst_mismatch = FormBase.DSTMismatch(Server.Metadata); } foreach (TaggedObject obj in results.TaggedOutput) { Stream stream = new Stream(); stream.FromStreamsCmdTaggedOutput(obj,offset, dst_mismatch); value.Add(stream); } return value; } else { P4Exception.Throw(results.ErrorList); } return null; } /// /// Delete a stream from the repository /// /// The stream to be deleted /// Only the '-f' flag is valid when deleting an existing stream /// /// To delete a locked stream with no child streams or active clients as an admin user: /// /// Stream stream = rep.GetStream("//Rocket/GUI"); /// StreamCmdOptions opts = new StreamCmdOptions(StreamCmdFlags.Force, /// null, null); /// rep.DeleteStream(stream, opts); /// /// public void DeleteStream(Stream stream, Options options) { if (stream == null) { throw new ArgumentNullException("stream"); } P4Command cmd = new P4Command(this, "stream", true, stream.Id); if (options == null) { options = new Options((StreamCmdFlags.Delete), null, null); } if (options.ContainsKey("-d") == false) { options["-d"] = null; } P4CommandResult results = cmd.Run(options); if (results.Success == false) { P4Exception.Throw(results.ErrorList); } } /// /// Get the integration status for a stream in the repository /// /// The stream to get integration status on /// options for the istat command /// The integration status of the stream /// ///
p4 help istat ///
///
istat -- Show/cache a stream's integration status ///
///
p4 istat [ -a -c -r -s ] stream ///
///
'p4 istat' shows a stream's cached integration status with respect ///
to its parent. If the cache is stale, either because newer changes ///
have been submitted or the stream's branch view has changed, 'p4 ///
istat' checks for pending integrations and updates the cache before ///
showing status. ///
///
Pending integrations are shown only if they are expected by the ///
stream; that is, only if they are warranted by the stream's type ///
and its fromParent/toParent flow options. (See 'p4 help stream'.) ///
///
The -r flag shows the status of integration to the stream from its ///
parent. By default, status of integration in the other direction is ///
shown, from the stream to its parent. ///
///
The -a flag shows status of integration in both directions. ///
///
The -c flag forces 'p4 istat' to assume the cache is stale; it ///
causes a search for pending integrations. Use of this flag can ///
impact server performance. ///
///
The -s flag shows cached state without refreshing stale data. ///
///
///
/// /// /// Get the direction of integration for stream "//Rocket/GUI" with respect /// to its parent: /// /// /// Stream s = rep.GetStream("//Rocket/GUI",null,null); /// StreamMetaData smd = rep.GetStreamMetaData(s, null); /// StreamMetaData.IntegAction action = smd.IntegToParentHow; /// /// /// /// Get the direction of integration for stream "//Rocket/GUI" from its parent: /// /// /// Stream s = rep.GetStream("//Rocket/GUI",null,null); /// StreamMetaData smd = rep.GetStreamMetaData(s,new Options(GetStreamMetaDataCmdFlags.Reverse)); /// StreamMetaData.IntegAction action = smd.IntegFromParentHow; /// /// /// public StreamMetaData GetStreamMetaData(Stream stream, Options options) { if (stream == null) { throw new ArgumentNullException("stream"); } P4Command cmd = new P4Command(this, "istat", true, stream.Id); P4CommandResult results = cmd.Run(options); if (results.Success) { if ((results.TaggedOutput == null) || (results.TaggedOutput.Count <= 0)) { return null; } StreamMetaData value = new StreamMetaData(); value.FromIstatCmdTaggedData((results.TaggedOutput[0])); return value; } else { P4Exception.Throw(results.ErrorList); } return null; } } }